# Docker toolchain

> **TL;DR**
> Platforms: macOS / Linux / Windows / WSL
>
>
>
> Project model: [CMake](quick-cmake-tutorial.html) / [Makefile](makefiles-support.html)

For the purpose of development in Docker containers, CLion provides full Docker integration via the dedicated Docker [toolchain](how-to-create-toolchain-in-clion.html). Watch this video to learn more:

[Video](https://www.youtube.com/v/p7Bi-mOyelM)

> **Note:**
> Docker toolchain is not available for remote TCP and SSH connections. To work with containers running remotely, use [Remote with Gateway](remote.html) or [Remote with local sources](remote-projects-support.html).

Procedure: Sample Dockerfile

To help you get started with Docker development in CLion, we created an [example Dockerfile](https://github.com/JetBrains/clion-remote/blob/master/Dockerfile.cpp-env-ubuntu) for the case of Ubuntu base image. You can copy this file to your project and adjust for your needs or just use it as a reference.

The example file includes the following lines and sections:

* In the comments at the top, you can find the commands for [building](#build-and-run) the container.

* The `FROM ubuntu:20.04` line refers to the container's base image.

* The `apt-get` part installs all the toolchain dependencies into the container. Here you can adjust the tools and their versions.

> **Tip:**
> On Linux, when Docker is not rootless, CLion uses the host UID due to to [file permission limitations when writing to volumes from Docker containers](https://dille.name/blog/2018/07/16/handling-file-permissions-when-writing-to-volumes-from-docker-containers/).
>
>
>
> As a workaround, you can configure the Docker daemon as rootless or create a parametrized user in the Dockerfile, for example:
>
>
>
>
> ```DOCKERFILE
> ARG UID=1000
> RUN useradd -m -u ${UID} -s /bin/bash builder
> USER builder
> ```
>
>
>
> And then build the image with the new UID:
>
>
>
>
> ```DOCKERFILE
> docker build --build-arg UID=$(id -u) ...
> ```

Procedure: Build the container

> **Tip:**
> Another option is to use a pre-built container from [docker registry](https://docs.docker.com/registry/).

* Run the `docker build` command from the top of the Dockerfile:

```
docker build -t clion/ubuntu/cpp-env:1.0 -f Dockerfile.cpp-env-ubuntu .
```

Depending on your platform and your Docker setup, you may need to run it using `sudo`.

This command will build the Ubuntu base image with proper toolchain dependencies.

Procedure: Create a Docker toolchain

1. Go to `Settings | Build, Execution, Deployment | Toolchains`.

Click ![Add toolchain](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) and select Docker:

![Adding a Docker toolchain](https://resources.jetbrains.com/help/img/idea/2026.2/cl_docker_toolchain_add.png)

2. Click the gear button to the Server field to add a Docker image:

![Add a Docker image](https://resources.jetbrains.com/help/img/idea/2026.2/cl_docker_toolchain_add_image.png)

> **Note:**
> Out of the options listed in Connect to Docker daemon with, only the local one (first) can be used in CLion as a toolchain. For remote Docker, we recommend using [remote with local sources](remote-projects-support.html).

You can also configure a Docker server in `Settings | Build, Execution, Deployment | Docker` and then select it in the toolchain settings.

3. Select the Docker image and wait until the tools detection finishes.

![Docker toolchain configured](https://resources.jetbrains.com/help/img/idea/2026.2/cl_docker_toolchain_configured.png)

Use the Container Settings field to provide additional container settings, such as port and volume bindings:

![Docker container settings](https://resources.jetbrains.com/help/img/idea/2026.2/cl_dockertoolchain_containersettings.png)

> **Tip:**
> See [Docker plugin integration](docker.html) for the description of the Services tool window and Docker-specific IDE actions.
>
> ![Docker Services tool window](https://resources.jetbrains.com/help/img/idea/2026.2/cl_docker_services.png)

Procedure: Build, run, debug with a Docker toolchain

After configuring a Docker toolchain, you can select it in [CMake profiles](cmake-profile.html) or in [Makefile settings](makefiles-support.html#makefile-settings). Alternatively, move the toolchain to the top of the list to make it default.

![Docker toolchain in a CMake profile](https://resources.jetbrains.com/help/img/idea/2026.2/cl_docker_toolchain_cmake_profile.png)

* The project folder will be mounted to the Docker container, and build/run/debug will be performed inside it. By default, the project folder is mounted into the `/tmp` folder in the container. However, if there are path mappings specified in the [toolchain](#create-docker-toolchain), CLion will use them instead. For example, if the project root is `/data/code/project` and toolchain path mapping is `/data/code` -> `/code`, then CLion will reuse this mapping and will not mount the project into `/tmp/project`. > **Tip:** > In addition to project root, CLion also mounts the following folder: > > > > `$TMPDIR/<major>_<minor>/Docker/<imageName>_<imageTag>`

* CLion will start the container and shut it down after the command is executed.

Procedure: Bind mounts on SELinux

You can add `:z` configuration flags to Docker bind mount to connect files and folders to containers running on workstations with SELinux enabled. This allows CMake and other tools to access your project files and other files on the system.

1. Go to `Settings/Preferences | Advanced Settings | Docker`.

2. Set the corresponding checkbox:

![Binding for SELinux systems](https://resources.jetbrains.com/help/img/idea/2026.2/docker_selinux_advsetting.png)

> **Tip:**
> Find more details in [Docker containers: Bind mounts on SELinux](docker-containers.html#bind_mounts_selinux).

Procedure: Improve Docker toolchain performance on Windows

To get better performance on Windows, we recommend using Docker with the WSL 2 backend.

1. Set up [Docker Desktop with the WSL 2 backend](https://docs.docker.com/desktop/windows/wsl/).

2. In the Docker desktop application, navigate to `Settings | Resources | WSL Integration` and enable integration with your WSL distribution (for example, `ubuntu-20.04`).

3. Place the project sources into the WSL filesystem (for example, `\\wsl$\ubuntu-20.04\tmp\llvm`), then open it in CLion and configure a Docker toolchain.

Procedure: Enable debug output for Docker in WSL

To get debug output when debugging with a Docker toolchain inside WSL, you need to make changes in `wsl.conf`.

1. Open the WSL shell.

2. Open the `wsl.conf` file for editing:

```CONSOLE
sudo $EDITOR /etc/wsl.conf
```

3. Add the following lines:

```CONSOLE
[automount]
root = /mnt
crossDistro = true
options = "metadata"
```

4. Save the changes.

5. Restart WSL. You can do that by running `wsl -t <distribution_name>`.

## Alternative workflow: develop in Docker using remote with local sources

> **Note:**
> Normally, we recommend that you use the Docker toolchain as described above. This alternative approach may be helpful in rare cases, for example, when you face performance issues on Windows and WSL 2 backend is not available for some reasons.

In this case, Docker-based toolchains are configured via [remote with local sources](remote-projects-support.html). The container should be running with an SSH daemon.

[Video](https://www.youtube.com/v/h69XLiMtCT8)

> **Tip:**
> Instructions below are a brief summary of the [Using Docker with CLion](https://blog.jetbrains.com/clion/2020/01/using-docker-with-clion/) blog post.

### Sample Dockerfile for remote scenario

Use the [remote-cpp-env](https://github.com/JetBrains/clion-remote/blob/master/Dockerfile.remote-cpp-env) example file. It includes two additional sections:

* The `ssh` section sets up the SSH for CLion to connect into.

* The `user` section creates a user into the container.

Procedure: 1. Build the container

1. Use the `docker build` line from the top of the Dockerfile:

```
docker build -t clion/remote-cpp-env:0.5 -f Dockerfile.remote-cpp-env .
```

Depending on your platform and your Docker setup, you may need to run it using `sudo`.

This command will build the Ubuntu base image with proper toolchain dependencies, set up SSH, and create the user.

Procedure: 2. Run the container

1. Use the next command, `docker run`:

```
docker run -d --cap-add sys_ptrace -p127.0.0.1:2222:22 --name clion_remote_env clion/remote-cpp-env:0.5
```

In this line, `-d` runs the container as a daemon and `--cap-add sys_ptrace` adds the `ptrace` capability, which is necessary for debugging.

The `-p` part specifies a port mapping. It exposes the default SSH port inside the container (22) as port 2222 on the host environment. You can specify any available port numbers here.

2. (Optional) You can create mapped volumes using the `-v` flag: `-v /local/path/to/project:/remote/path/to/project`

After that, go to `Settings | Build, Execution, Deployment | Deployment`, change the connection type to Local or mounted folder, and set the path mappings. See [Remote with local sources: Check and adjust the deployment configuration](remote-projects-support.html#deployment-entry).

Procedure: 3. Clear cached SSH keys

1. Last step of building and running the container is the `ssh-keygen` command, which clears any cached SSH keys. This is important since localhost ports are only temporarily mapped and can be reused by different containers.

```
ssh-keygen -f "$HOME/.ssh/known_hosts" -R "[localhost]:2222"
```

Procedure: 4. Create a Remote Host toolchain

At this point, the container is running with an SSH server daemon, and you can connect into it using CLion’s standard Remote Development features.

1. Follow the general instructions on [creating a remote toolchain](remote-projects-support.html#remote-toolchain).

In the Credentials field, set up the SSH configuration:

* Host - localhost

* Port - 2222

* User name / Password - as specified in the Dockerfile

2. After establishing the connection, CLion attempts to detect the toolchain. Since the tools were installed into default locations, they will be detected automatically.

If you change the `apt-get` part of the Dockefile to install the tools into other locations, provide the paths in the Make, C Compiler, C++ Compiler, and Debugger fields.

3. Create a [CMake profile that uses the remote toolchain](remote-projects-support.html#CMakeProfile). Wait for the project to reload.

> **Note:**
> If you get an error message "CMake 3.15 or higher is required", it means that the container has an earlier version of CMake than your local project. You can change the version back at the top of the `CMakeLists.txt` file. As a more complicated alternative, build CMake of a higher version inside the container or use a different base image.

After the files get transferred into the container, you will be able to select the profile in the Run/Debug configuration switcher to build, run, or debug your code inside the container using the specified toolchain.

> **Tip:**
> By default, your project code is transferred into the container at default locations. To change the default paths, use the Mappings tab of the [deployment entry](remote-projects-support.html#deployment-entry).

## See also

### How tos

[Remote development overview](remote-development.html)

### Procedures

[Docker plugin](docker.html)

### External Links

[Watch Docker Toolchain in Action](https://blog.jetbrains.com/clion/2021/12/docker-toolchain/)