django and pycharm

Debugging a Containerized Django App in PyCharm

Debugging a Containerized Django App in PyCharm

Developing your Django app in Docker can be very convenient. You don't have to install extra services like Postgres, Nginx, and Redis, etc. on you own machine. It also makes it much easier for a new developer to quickly get up and running.

The grass is not always greener, though. Running Django in Docker can create some problems and make what was once easy difficult. For example, how do you set breakpoints in your code and debug?

In this quick tutorial, we'll look at how PyCharm comes to the rescue with its remote interpreter and Docker integration to make it easy to debug a containerized Django app.

This post uses PyCharm Professional Edition v2020.1.1. For the differences between the Professional and Community (free) Editions of PyCharm, take a look at the Professional vs. Community - Compare Editions guide.



By the end of this tutorial, you should be able to do the following in PyCharm:

  1. Configure Docker settings
  2. Set up a Remote Interpreter
  3. Create a Run/Debug configuration to debug a Django app running inside of Docker

Docker Settings in PyCharm

The first step we need to do is to tell PyCharm how to connect to Docker. To do so, open PyCharm settings (PyCharm > Preferences for Mac users or File > Settings for Windows and Linux users), and then expand the "Build, Execution, Deployment" setting. Click "Docker" and then click the "+" button to create a new Docker configuration.

PyCharm preferences

For Mac, select the Docker for Mac options. Then apply the changes.

Setup a Remote Interpreter

Now that we have the Docker configuration set up, it's time to configure Docker Compose as a remote interpreter. Assuming you have a project open, open the settings once again and expand the "Project <your-project-name>" setting and click "Project Interpreter". Click the gear icon and choose "Add".

PyCharm preferences interpreter

In the next dialog, choose "Docker Compose" in the left pane, and select the Docker configuration you created in the previous steps in the "Server" field. The "Configuration file(s)" field should point to your Docker Compose file while the "Service" field should point to the web application service from your Docker Compose file.

For example, if your Docker Compose file looks like this, then you'll want to point to the web service:

version: '3.7'

    build: ./app
    command: python runserver
      - ./app/:/usr/src/app/
      - 8008:8000
      - ./
      - db
    image: postgres:12.0-alpine
      - postgres_data:/var/lib/postgresql/data/
      - POSTGRES_USER=hello_django
      - POSTGRES_PASSWORD=hello_django
      - POSTGRES_DB=hello_django_dev


The debugger attaches specifically to the web service. All other services in your Docker Compose file will start when we later run the configuration in PyCharm

Add interpreter

Click "OK" to apply the changes.

Back in the "Project Interpreter" setting dialog you should now see that the project has a remote interpreter.

Remote interpreter

Close the settings.

Create a Run/Debug Configuration

Now that we've configured PyCharm to be able to connect to Docker and created a remote interpreter configuration based on the Docker Compose file, we can create a Run/Debug configuration.

Click on the "Add configuration..." button at the top of the PyCharm window.

Add run configuration

Next click the "+" button and choose "Django server".

Add run configuration step 2

Give the configuration a name. The important thing in this configuration dialog is to set the "Host" field to

Add run configuration step 3

Click "OK" to save the configuration. We can now see the Run/Debug configuration at the top of the PyCharm window and that the buttons (for run, debug, etc.) are enabled.

The finished run configuration

If you now set breakpoints in your Django app and press the debug button next to the Run/Debug configuration, you can debug the Django app running inside the Docker container.

Debugging in the Docker container


In this tutorial, we've shown you how to configure PyCharm for debugging a Django app running inside of Docker. With that, you can now not only debug your views and models and what not, but also set breakpoints and debug your template code.

TIP: Want to supercharge your debugging even more? PyCharm also lets you set conditional breakpoints!

Docker Django

Join our mailing list to be notified about course updates and new tutorials.


Authentication with Flask, React, and Docker

Get the full course. Learn how to add authentication to a Flask and React microservice.

View the Course

Authentication with Flask, React, and Docker

Get the full course. Learn how to add authentication to a Flask and React microservice.

Table of Contents