How to use a debugger with Django web applications¶

This guide describes how to attach a debugger to Django applications based around our standard boilerplate application environment.

Important

Your application must be based on version 2.8.0 later of our web application boilerplate. If this is not the case, use copier to update the application environment.

Check that debugpy is enabled¶

The standard boilerplate enables the debugpy debugger when running in development. You can check that is the case by ensuring:

Ensure there is a line in Dockerfile which enables the debugger. This line should look like:

ENTRYPOINT ["python3", "-Xfrozen_modules=off", "-m", "debugpy", "--listen", "0.0.0.0:5678"]

Ensure that the port 5678 is forwarded in docker-compose.py. There should be an entry like 5678:5678 in the ports section of the webapp service.

Configure your IDE¶

You will need to configure your IDE to attach a Python debugger to localhost using port 5678. How this is done will depend on your IDE.

You may want to additionally configure your IDE to launch the application by running poe up but you can still start from the terminal as usual.

VS Code or Neovim¶

If you are using VS Code or Neovim with the nvim-dap package installed, create a file named .vscode/launch.json:

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to web application",
      "type": "debugpy",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "."
        }
      ]
    }
  ]
}

Tip

If .vscode is not already in your .gitignore, add .vscode/ to .git/local/exclude to avoid accidentally adding this file to a commit.

Start debugging¶

Start the application via poe up as usual. Trigger your IDE to start debugging. For example, the default key binding in VS Code is F5.

Your IDE should connect to debugpy and allow inspection, setting breakpoints, etc. as usual.

Summary¶

In this guide you learned how to ensure that debugging is enabled for our standard Django web application and how to configure some IDEs to connect to the debugger.