Limitations

Last modified: 13 February 2025

There are several limitations that you need to keep in mind when working with Dev Containers.

Dev Containers on Windows

Dev Container images based on the Windows OS are not supported.

Creating Dev Containers from a VCS project

When you start a Dev Container from a VCS project, the following steps occur under the hood:

Build a Dev Container

  1. Prepare the helper container for git clone.

  2. Clone into the Docker volume.

  3. Create the tmp working directory.

  4. Extract the build context from the volume.

  5. Docker gets the context for the Dev Container building.

  6. Clean up a temporary working directory.

To avoid errors in the devcontainer.json properties, Docker file, and Docker-compose related to a mount process and relative paths, we list all the build steps and include a warning suggesting to check your Dev Container configuration.

Check the following warning example:

WARNING: Mount from /var/folders/0h/f3gs9sz96xdbqnp63t7bs4b80000gn/T/jb_devcontainer_sources_12dc6d53a2ae8fac66e0a54e76f501464151078046496127718/DevCont_templates/.devcontainer
to /workspaces is referenced to temporary folder used for build. This may lead to unexpected behaviour
or not working devcontainer. Please check that your devcontainer configuration is expected for
build from git repository.

Run Container inside the remote IDE

A scenario of creating a Dev Container from the running backend-client connection is not supported.

For example, you connected to your remote project using the SSH connection and you've added a devcontainer.json. There is no option to start a Dev Container from the created devcontainer.json file.

However, you can use the following procedure as a workaround:

Create a Dev Container on the remote machine

  1. Create a Docker connection to SSH.

  2. Install the Docker CLI locally.

    On Windows, you can install it without the Docker desktop; we do not need the Docker daemon, we need only Docker CLI.

  3. Commit all changes from the SSH machine to Git.

  4. Create a Dev Container by using remote server and the git clone command.

XDG_* environment variables on the remote backend

The following environment variables are used by the remote backend IDE and cannot be reassigned in the devcontainer.json configuration file:

XDG_CACHE_HOME
XDG_CONFIG_HOME
XDG_DATA_HOME