Local debugging — Python

Last updated on April 8, 2026

This guide covers everything specific to debugging an Extend app written in Python. For concepts that apply to all Extend apps and languages — environment variables, VS Code debug workflow, log reading, and common issues — see the Extend local debugging guide.

Prerequisites​

  • Python 3.10 or later — verify with:

    python --version
    # Expected: Python 3.10.x or later

  • VS Code Python extension (ms-python.python) — install from the VS Code marketplace or accept the recommended extensions prompt when you open the repository.

  • debugpy — the Python debug adapter for VS Code:

    pip install debugpy

  • AccelByte credentials — AB_BASE_URL, AB_CLIENT_ID, AB_CLIENT_SECRET. See Environment setup in the main guide.

VS Code launch configuration​

The repository ships with a ready-to-use launch configuration in .vscode/launch.json:

{
  "name": "Debug: Service",
  "type": "python",
  "request": "launch",
  "module": "app",
  "cwd": "${workspaceFolder}/src",
  "envFile": "${workspaceFolder}/.env"
}

The exact module and cwd values are provided by the app template's .vscode/launch.json.

Steps:

  1. Fill in .env (see Environment setup).
  2. Open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D).
  3. Select "Debug: Service" from the dropdown.
  4. Press F5.

Other IDEs — remote debugpy attach​

Start the app with debugpy listening on port 5678:

export $(grep -v '^#' .env | xargs)
python -m debugpy --listen 5678 --wait-for-client -m app

The process pauses until a debugger connects. Attach from PyCharm or a second VS Code window:

{
  "name": "Attach: Remote",
  "type": "python",
  "request": "attach",
  "connect": { "host": "localhost", "port": 5678 }
}

Conditional breakpoint syntax​

Right-click a breakpoint → Edit Breakpoint → enter a Python expression. Example:

request.user_id == "user_001"

The debugger only pauses when the condition is true.

Reading logs with jq​

# Pretty-print everything
python -m app 2>&1 | jq '.'

# Show only ERROR lines
python -m app 2>&1 | jq 'select(.level == "ERROR")'

For an overview of the log format and log levels, see Reading and understanding logs in the main guide.

Python-specific troubleshooting​

ModuleNotFoundError for app​

Symptom: Running python -m app gives ModuleNotFoundError: No module named 'app'.

Cause: The working directory is wrong. The module lives under src/.

Fix:

cd src
python -m app

Or set PYTHONPATH:

PYTHONPATH=src python -m app

debugpy not found​

Symptom: VS Code says debugpy is not installed.

Fix:

pip install debugpy
# If using a virtual environment, activate it first:
source .venv/bin/activate && pip install debugpy

Checking for port conflicts​

ss -tlnp | grep -E '6565|8000|8080|5678'

Kill any stale process and start again.

References​

Last updated on
On this page