Configure an interpreter using Docker Compose

Last modified: 24 March 2025

Available only in PyCharm Professional: download to try or compare editions

Prerequisites

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 macOS installation.

    Note that you might want to repeat this tutorial on different platforms; then use Docker installations for Windows 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 settings page  as described in Install plugins.

    In the Settings dialog () , select Build, Execution, Deployment | Docker, and select Docker for <your operating system> under Connect to Docker daemon with. For example, if you are 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.

Prepare an example

Enable the Django plugin

This functionality relies on the Django plugin, which is bundled and enabled in PyCharm by default. If the relevant features are not available, make sure that you did not disable the plugin.

  1. Press to open settings and then select Plugins.

  2. Open the Installed tab, find the Django plugin, and select the checkbox next to the plugin name.

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

  1. On the Welcome screen, click Get from VCS.

  2. In the Get from Version Control dialog, specify the URL of the remote repository and click Clone.

  3. PyCharm suggests 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.

  4. Another hint that IDE provides is detecting a data source. Click Connect to Database to set up the database.

    Detecting a datasource

    You might need to download missing drivers and check the rest of the configuration options:

    Configuring a datasource

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 the database, and one for the application itself. The Docker Compose will link the two containers together.

Add 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", "manage.py", "runserver", "0.0.0.0:8000"]

  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

    tip

    If needed, you can use variable substitution in the docker-compose.yml file, for example:

    db:
image: "postgres:${POSTGRES_VERSION}"

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

Configure Docker

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

  1. Press to open settings and then select Build, Execution, Deployment | Docker.

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

    Docker settings

    If you installed Docker in a custom location, you may need to specify the paths to the Docker CLI executables.

    note

    The Path mappings settings are not available on Linux. So, if you want to map some directories on a virtual machine to some path on your local Linux machine, you will have to do it manually.

    Click OK to save changes.

Configure 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 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 Docker configuration in the Server dropdown.

  4. Specify the docker-compose.yml file in Configuration files and select the service.

    Creating a new Docker Compose target

    Optionally, specify environment variables and edit the Compose project name.

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

    Configuring a Docker Compose target

  6. 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.

Use the Docker tool window

When you have configured Docker, the Services tool window appears at the bottom of PyCharm's main window. You can click docker-compose up docker-compose up 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.

Configure database credentials

Modify the DATABASES section of the settings.py 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'
    }
}

Run the application

  1. Select Tools | Run 'manage.py' task from the main menu and enter migrate to run a migration and execute a Django application.

  2. Create a Run/Debug configuration for the Django server. To do that, select Run | Edit Configurations from the main menu.

    In the Run/Debug Configurations dialog, click Add Run/Debug configuration for a Django Server Add New Configuration and select Django Server.

    Run/Debug configuration for a Django server

  3. Set the Host field to 0.0.0.0 to ensure that the Docker container is open to external requests. To allow the server to start at this address, add 0.0.0.0 to the ALLOWED_HOSTS list in settings.py.

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

    Docker compose run

To see the output in your web browser, go to http://localhost:8000:

Django application output

tip

If you are using the Docker Machine, use the machine's IP address instead.

note

You can also create Run/Debug Configurations for Django tests.

Debug the application

With the Run/Debug configuration created, you can also debug your application.

  1. Set a breakpoint (for a Django application, you can set it in a template).

  2. Do one of the following:

    • Select Run | Debug 'RunDjangoApp' from the main menu.

    • Click Start Debugger Debug next to the Run/Debug configuration drop-down with the RunDjangoApp configuration selected.

For more information about debugging application in a container, refer to Debugging in a Docker container.

See also

Related

Tutorials and Examples