PyCharm 2023.1 Help

Configure an interpreter using Docker Compose


Make sure that the following prerequisites are met:

  • You have stable Internet connection, so that PyCharm can download and run busybox:latest (the latest version of the BusyBox Docker Official Image). Once you have successfully configured an interpreter using Docker, you can go offline.

  • Docker is installed. You can install Docker on the various platforms, but here we'll use the Windows installation.

    Note that you might want to repeat this tutorial on different platforms; then use Docker installations for macOS and Linux (Ubuntu, other distributions-related instructions are available as well).

  • Before you start working with Docker, make sure that the Docker plugin is enabled. The plugin is bundled with PyCharm and is activated by default. If the plugin is not activated, enable it on the Plugins page of the IDE settings Ctrl+Alt+S as described in Install plugins.

    In the Settings dialog (Ctrl+Alt+S), select Build, Execution, Deployment | Docker, and select Docker for <your operating system> under Connect to Docker daemon with. For example, if you're on macOS, select Docker for Mac. See more detail in Docker settings.

Note that you cannot install any Python packages into Docker-based project interpreters.

Preparing an example

Let's use a Django application with a PostgreSQL database running in a separate container.

  1. Press Ctrl+Alt+S to open the IDE settings and select Languages & Frameworks | Django. Ensure that the Enable Django Support checkbox is selected. Then click OK to close the project settings.

  2. Download the project archive from GitHub, unpack it, and save it on the local drive.

  3. Select File | Open from the main menu and specify the path to the downloaded project.

  4. PyCharm can suggest creating a virtual environment based on the project requirements recorded in the requirements.txt file.

    Creating a virtual environment

    Click OK to create an environment.

With this done, your example is ready, and you can start configuring docker containers. For this Django application, let's create two containers: one for a database, and one for the application itself. The Docker Compose will link the two containers together.

Adding files for Docker and Docker Compose

  1. In the Project tool window, right-click the project root and select New | File from the context menu. Enter the filename: Dockerfile.

  2. Copy and paste the following code in the Dockerfile file:

    FROM python:3.6.7 WORKDIR /app # By copying over requirements first, we make sure that Docker will cache # our installed requirements rather than reinstall them on every build COPY requirements.txt /app/requirements.txt RUN pip install -r requirements.txt # Now copy in our code, and run it COPY . /app EXPOSE 8000 CMD ["python", "", "runserver", ""]
  3. Then right-click the project root again, select New | File from the context menu, and create the docker-compose.yml file.

  4. Copy and paste the following code into the docker-compose.yml file.

    version: '2' services: web: build: . ports: - "8000:8000" volumes: - .:/app links: - db db: image: "postgres:9.6" ports: - "5432:5432" environment: POSTGRES_PASSWORD: hunter2

    This file defines two services: web and db, and links them together.

    docker-compose file

Configuring Docker

Now that you've prepared the example, let's configure Docker.

  1. Press Ctrl+Alt+S to open the IDE settings and select Build, Execution, Deployment | Docker.

  2. Click Add a docker server to create a Docker server. Accept the suggested default values:

    Docker settings for macOS
    Docker settings for Windows

    Click OK to save changes.

Configuring Docker Compose as a remote interpreter

Let's now define a remote interpreter based on Docker-Compose.

  1. Do one of the following:

    • Click the Python Interpreter selector and choose Add New Interpreter.

    • Press Ctrl+Alt+S to open Settings and go to Project: <project name> | Python Interpreter. Click the Add Interpreter link next to the list of the available interpreters.

    • Click the Python Interpreter selector and choose Interpreter Settings. Click the Add Interpreter link next to the list of the available interpreters.

  2. Select On Docker Compose.

  3. Select an existing Docker configuration in the Server dropdown.

    Alternatively, select Create new and perform the following steps to create a new Docker configuration:

    Create a Docker configuration

    Click New to add a Docker configuration and specify how to connect to the Docker daemon.

    The connection settings depend on your Docker version and operating system. For more information, see Docker connection settings.

    The Connection successful message should appear at the bottom of the dialog.

    Docker connection settings

    For more information about mapping local paths to the virtual machine running the Docker daemon when using Docker on Windows or macOS, see Virtual machine path mappings for Windows and macOS hosts. You will not be able to use volumes and bind mounts for directories outside of the mapped local path.

    This table is not available on a Linux host, where Docker runs natively and you can mount any directory to the container.

  4. In Configuration files, specify the docker-compose.yml file. Also select the service.

    Creating a new Docker Compose target

    Optionally, specify environment variables.

  5. Wait until PyCharm creates and configures a new target:

                                    a Docker Compose target
  6. Next, select an interpreter to use in the container. You can choose any virtualenv or conda environment that is already configured in the container, or select a system interpreter.

    Selecting a system interpreter for a Docker target
  7. Click OK.

    The configured remote interpreter is added to the list.

Using the Docker tool window

Since you've configured Docker, the Services tool window appears at the bottom of PyCharm's main window. You can click run all services in the gutter next to the services group to launch db and web services.

Docker window

Refer to Docker for more details on managing docker containers in the Services tool windows.

Configuring database credentials

Modify the DATABASES section of the file in your Django project to add database configuration details:

DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'postgres', 'USER': 'postgres', 'PASSWORD': 'hunter2', 'HOST': 'db' } }

Running your application under Docker-Compose

  1. To execute a Django application, run a migration. Select Tools | Run '' task from the main menu and enter migrate: task is running in the Docker

    (See Run tasks of for details.)

  2. Create a run/debug configuration for the Django server. To do that, from the main menu select Run | Edit Configurations. In the dialog that opens click Add Run/Debug configuration for a Django Server and select Django Server:

    Run/Debug configuration for a Django server

    The Host field must be set to — to make sure that we listen to requests coming from outside the Docker container. To allow the server to start at this address, add to the ALLOWED_HOSTS list in

  3. To run the newly created configuration, select Run | Run 'RunDjangoApp' from the main menu.

    Docker compose run

To see output in your web browser, go to http://localhost:8000 (in the address bar, change to localhost):

Django application output

With the run/debug configuration created, you can also debug your application under Docker Compose. To do that, set a breakpoint (for a Django application, you can set it in a template) and from the main menu select Run | Debug 'RunDjangoApp', or just click Start Debugger next to the run/debug configuration drop-down with the RunDjangoApp run/debug configuration selected.

Debugging in a docker container

For more details on debugging application in a container , see Debugging in a Docker container.


Let's summarize what has been done with the help of PyCharm:

  • We downloaded a Django application from GitHub and opened it.

  • We added specific Docker Compose files to our project.

  • We configured a remote interpreter based on Docker Compose.

  • We ran our Django application in the Docker Compose container.

Last modified: 21 April 2023