Debug Python within a container

When adding Docker files to a Python project, tasks and launch configurations are added to enable debugging the application within a Docker container. To accommodate the various scenarios of Python projects, some apps may require additional configuration.

Configuring the Docker container entry point

You can configure the entry point of the Docker container by setting properties in tasks.json. VS Code automatically configures the container entry point when you first use the Docker: Add Docker Files to Workspace... command.

Example: Configuring the entry point for a Python module

{
  "tasks": [
    {
      "type": "docker-run",
      "label": "docker-run: debug",
      "dependsOn": ["docker-build"],
      "python": {
        "module": "myapp"
      }
    }
  ]
}

Example: Configuring the entry point for a Python file

{
  "tasks": [
    {
      "type": "docker-run",
      "label": "docker-run: debug",
      "dependsOn": ["docker-build"],
      "python": {
        "args": ["runserver", "0.0.0.0:8000", "--nothreading", "--noreload"],
        "file": "manage.py"
      }
    }
  ]
}

Automatically launching the browser to the entry page of the application

You can select the Docker: Python - Django or Docker: Python - Flask launch configurations to automatically launch the browser to the main page of the app. This feature is enabled by default, but you can configure this behavior explicitly by setting the dockerServerReadyAction object in launch.json.

This feature depends on several aspects of the application:

  • The application must output to the debug console or Docker logs.
  • The application must log a "server ready" message.
  • The application must serve a browsable page.

Here is an example of using dockerServerReadyAction to launch the browser to open the about.html page based on a specific server message pattern:

{
  "configurations": [
    {
      "name": "Docker: Python - Django",
      "type": "docker",
      "request": "launch",
      "preLaunchTask": "docker-run: debug",
      "python": {
        "pathMappings": [
          {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/app"
          }
        ],
        "projectType": "django"
      },
      "dockerServerReadyAction": {
        "action": "openExternally",
        "pattern": "Starting development server at (https?://\\S+|[0-9]+)",
        "uriFormat": "%s://localhost:%s/about.html"
      }
    }
  ]
}

Note: The regex found in the pattern attribute simply attempts to capture a logged message similar to "Starting development server at http://localhost:8000". It accommodates variations in the url for http or https, any host name, and any port.

Important dockerServerReadyAction object properties

  • action: The action to take when the pattern is found. Can be debugWithChrome or openExternally.

  • pattern: If the application logs a different message than shown above, set the pattern property of the dockerServerReadyAction object to a JavaScript regular expression that matches that message. The regular expression should include a capture group that corresponds to the port on which the application is listening.

  • uriFormat: By default, the Docker extension will open the main page of the browser (however that is determined by the application). If you want the browser to open a specific page like the example above, the uriFormat property of the dockerServerReadyAction object should be set to a format string with two string tokens to indicate the protocol and port substitution.

How to enable hot reloading in Django or Flask apps

When you select Docker: Add Docker Files to Workspace for Django or Flask, we provide you a Dockerfile and tasks.json configured for static deployment. Each time you make changes to your app code, you need to rebuild and re-run your container. Hot reloading allows you to visualize changes in your app code as your container continues to run. Enable hot reloading with these steps:

For Django Apps

  1. In the Dockerfile, comment out the line that adds app code to the container.

    #ADD . /app
  2. Within the docker-run task in the tasks.json file, create a new dockerRun attribute with a volumes property. This will create a mapping from the current workspace folder (app code) to the /app folder in the container.

    {
      "type": "docker-run",
      "label": "docker-run: debug",
      "dependsOn": [
        "docker-build"
      ],
      "dockerRun": {
        "volumes": [
          {
            "containerPath": "/app", "localPath": "${workspaceFolder}"
          }
        ]
      },
      ...
    }
  3. Edit the python attribute by removing --noreload and --nothreading.

    {
      ...
      "dockerRun": {
        "volumes": [
          {
            "containerPath": "/app", "localPath": "${workspaceFolder}"
          }
        ]
      },
      "python": {
        "args": [
          "runserver",
          "0.0.0.0:8000",
        ],
        "file": "manage.py"
      }
    }
  4. Select the Docker: Python – Django launch configuration and hit F5 to build and run your container.

  5. Modify and save any file.

  6. Refresh the browser and validate changes have been made.

For Flask Apps

  1. In the Dockerfile, comment out the line that adds app code to the container.

    #ADD . /app
  2. Within the docker-run task in the tasks.json file, edit the existing dockerRun attribute by adding a FLASK_ENV in the env property as well as a volumes property. This will create a mapping from the current workspace folder (app code) to the /app folder in the container.

    {
      "type": "docker-run",
      "label": "docker-run: debug",
      "dependsOn": [
        "docker-build"
      ],
      "dockerRun": {
        "env": {
          "FLASK_APP": "path_to/flask_entry_point.py",
          "FLASK_ENV": "development"
        },
        "volumes": [
          {
            "containerPath": "/app", "localPath": "${workspaceFolder}"
          }
        ]
      },
      ...
    }
  3. Edit the python attribute by removing --no-reload and --no-debugger.

    {
      ...
      "dockerRun": {
        "env": {
          "FLASK_APP": "path_to/flask_entry_point.py",
          "FLASK_ENV": "development"
        },
        "volumes": [
          {
            "containerPath": "/app", "localPath": "${workspaceFolder}"
          }
        ]
      },
      "python": {
        "args": [
          "run",
          "--host", "0.0.0.0",
          "--port", "5000"
        ],
        "module": "flask"
      }
    }
  4. Select the Docker: Python – Flask launch configuration and hit F5 to build and run your container.

  5. Modify and save any file.

  6. Refresh the browser and validate changes have been made.

How to debug your app with Gunicorn

The Docker: Python - Django and Docker: Python - Flask launch configurations automatically override the Gunicorn entry point of the container with the Python debugger. More information about Python debugger import usage can be found here.

To debug your app running with Gunicorn (or any other web server):

  1. Add debugpy to your requirements.txt file:

    debugpy
  2. Add the following code snippet to the file that you wish to debug:

    import debugpy
    debugpy.listen(5678)
    debugpy.wait_for_client()
  3. Add a Python: Remote Attach configuration to launch.json in the .vscode folder:

    {
      "name": "Python: Remote Attach",
      "type": "python",
      "request": "attach",
      "port": 5678,
      "host": "localhost",
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "/app"
        }
      ]
    }
  4. Save the launch.json file.

  5. Modify the docker-compose.yml file to expose the debugger port by adding 5678:5678 to the ports section. If you are using docker run to run your container from the terminal, you must append -p 5678:5678.

  6. Start the container by right-clicking on a docker-compose.yml file and selecting Compose Up or doing docker run from the command line.

  7. Set a breakpoint in the chosen file.

  8. Navigate to Run and Debug and select the Python: Remote Attach launch configuration.

  9. Hit F5 to attach the debugger.

Next steps

Learn more about: