Local debugging — Python

Last updated on May 26, 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:

    python3 --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. Modern VS Code versions bundle debugpy automatically. If it is missing:

    Install it ephemerally without modifying pyproject.toml:

    uv run --with debugpy python -m debugpy --version

  • 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: App",
  "type": "debugpy",
  "request": "launch",
  "module": "app",
  "cwd": "${workspaceFolder}",
  "env": { "PYTHONPATH": "src" },
  "envFile": "${workspaceFolder}/.env",
  "console": "integratedTerminal",
  "justMyCode": true
}

The exact configuration is provided by the app template's .vscode/launch.json — copy it from there if the values above differ.

Steps:

  1. Fill in .env (see Environment setup).
  2. Open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D).
  3. Select "Debug: App" 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)
PYTHONPATH=src uv run --with debugpy 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": "debugpy",
  "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 (Docker)
docker compose logs -f app | jq '.'

# Show only ERROR lines (Docker)
docker compose logs -f app | jq 'select(.level == "ERROR")'

Out-of-container:

PYTHONPATH=src uv run python -m app 2>&1 | jq '.'

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:

PYTHONPATH=src uv run python -m app

debugpy not found​

Symptom: VS Code says debugpy is not installed.

Fix:

uv add --dev 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