Whether alone or in a team, Python dependencies can be a headache and running old projects routinely fails if you are not carefully using virtual environments. On top your OS environment isn’t as stable as expected especially for Windows users. Docker containers are promising to be our savior if we are willing to spend the time and get into it.
Instead of explaining what Docker is or how it works I prepared a GitHub repository with the most minimal example on top of which you can build your own Docker container.
The goal is simple; run a docker container in Visual Studio Code to develop with Python under Windows 10.
Before getting started you need WSL2, Docker for Windows 10 and obviously Visual Studio Code. Here some helpful links without further details:
- WSL2 installation guide; Follow Manual Installation Step 1–5 (Step 6 not required)
- Docker Desktop; It is possible to run docker commands without the Docker Desktop App but this is the simplest way and I recommend it.
Check in your Docker Desktop Settings if the checkbox as shown on the image below is ticked. This will allow Docker to use your WSL that you just installed to run Linux containers.
Visual Studio Code
In case you don’t have Visual Studio Code installed you can get it here. There is a single extension you need to make the magic work: Remote Containers.
Run the devcontainer
From here things move fast. If you don’t have git on your Windows system get it here. Once you have git setup navigate to your directory you want to keep your project and clone the git repository below:
Open your project in Visual Studio Code and you should see a close to empty project like below:
To run the devcontainer hit the magic
CTRL+SHIFT+P buttons from Visual Studio Code an run
Remote-Containers: Open Folder in Container… . You’ll be prompted to select a folder in which case you need to choose the folder that contains
.devcontainer as seen on the image:
Congrats! Assuming I didn’t write a broken devcontainer your Docker image is being build and running. On the first run the process will take about 30 seconds but all subsequent runs are significantly faster. On the bottom left of your Visual Studio Code editor you should see text indicating that your container is being build, see the image below:
That’s all! You can now write Python code with the familiar Visual Studio Code interface.
To go back to your local environment hit
CTRL+SHIFT+P and run
Remote-Containers: Reopen Locally.
Adapting the devcontainer
The beating heart of our Docker environment is the
Dockerfile. I gave you the most minimal version of a
Dockerfile I could think of and will leave the tips and tricks to building a better one to more experienced people. Here is the complete
Dockerfile, yes all three lines:
FROM pythonCOPY . .RUN pip install -r .devcontainer/requirements.txt
Line 1: Takes an existing Docker image as the basis of the environment. In my case I choose the official Python Docker image. Alternatively you can use a Linux distribution like Ubuntu and install python, or other stuff, via
apt-get. Check out if a good container exists for your application on Docker Hub. As an example I needed to run GDAL with Python, which is surprisingly hard to install, and found a good container for my needs. All I had to do is copy the Docker image name (
thinkwhere/gdal-pythonin my case) and change the first line to
FROM <Docker Image>.
Line 2: Copies all the files in your
.devcontainer into the Docker container you are building. This matters so the
requirements.txt file is available inside the container for Line 3.
Line 3: Runs the command after
RUN which in the present case is installing all packages in the
requirements.txt file. To add new packages just write them into
requirements.txt or alternatively add
RUN pip install <package name> to the
The second relevant file is
devcontainer.json. Most importantly it will point at the location of your
Dockerfile. Beyond that you can tell Visual Studio Code to install additional extensions and set your Python settings. Admittedly I guessed my way through the Python settings so better check the devcontainer.json reference if you are interested in adapting it.
Running a devcontainer in Visual Studio Code isn’t really hard at all. However to build a really good environment a deeper knowledge of both
devcontainer.json is important.
Dockerfile I provide is bottom-tier! Learn from better people :)
It is important to adapt it and adopt best practices! You will no doubt get warnings by following the steps in this article (pylint, I/O performance, and their friends..). All the pieces are in place and with a good Docker image you can already code away.
Run Jupyter in your Docker container! (Spoilers: add
requirements.txt and run
jupyter notebook --allow-root).