Remote Python Development in Visual Studio Code

Dan Taylor

Today at PyCon 2019, Microsoft’s Python and Visual Studio Code team announced remote development in Visual Studio Code, enabling Visual Studio Code developers to work in development setups where their code and tools are running remotely inside of docker containers, remote SSH hosts, and Windows Subsystem for Linux (WSL), while you still get a rich and seamless user experience locally.

This support is currently available in Visual Studio Code Insiders builds, and is enabled by three new remote extensions in the Visual Studio Code marketplace:

  • Remote-Containers: develop in workspaces running inside of local docker containers
  • Remote-SSH: develop in workspaces running on a remote machine over an SSH connection
  • Remote-WSL: develop in workspaces running inside of Windows Subsystem for Linux

To get started download the remote extension pack, check out the Visual Studio Code Remote documentation, and dive right in! Check out the video below for a quick tour and keep on reading to learn more!

The ability to work with WSL and remote Python interpreters have long been the top requested features on our Python Extension GitHub page. We have heard from our Python users many different reasons why they need to work in remote workspaces: in the case of SSH their code needs access to large amounts of data, compute, GPUs, or other resources; with Docker they need to be able to create and switch between development environments with complex dependencies; and with WSL they may need tools and packages that are only available in a Linux environment.

With remote development, we’ve enabled all of these scenarios with remote Python interpreters and more: Visual Studio Code’s UI runs on your local machine and connects to a remote server which hosts your extensions remotely. This enables features like auto-completions, debugging, the terminal, source control, extensions you install, almost everything in Visual Studio Code runs seamlessly on the remote machine as if it was your local development workspace.

Remote Docker Workspaces and Dev Containers

Docker containers are a popular way to create reproducible development environments without having to install complex dependencies on your local machine. This also allows new team members to reproduce your environment by installing docker and opening your workspace in Visual Studio Code.

The “Remote – Containers” extension allows Visual Studio Code to work seamlessly in this development environment using the concept of dev containers. A dev container is defined by files in a .devcontainer folder and tells Visual Studio Code how to create a Docker environment for that workspace. You can use a Dockerfile to create a single container or a docker-compose.yml for running multiple containers.

To get started developing in a docker container, run the Remote-Containers: Open Folder in Containers… command and then browse to a folder on your local machine. If a .devcontainer folder is found in the workspace root, Visual Studio Code will create the dev container use the existing dev container definition.

If no container definition exists, you will be prompted to create a new dev container for that workspace. We have built-in definitions for Python developers that let you get started with Python 2/3, Python3+Postgres, Miniconda, and Anaconda:

A list of pre-made python containers: Python 2, Python 3, Anaconda, Miniconda, Python3 + PostgreSQL

Once you open a dev container, Visual Studio Code will create the docker image(s) and then installs a light-weight remote server and voilà, you are now coding inside of the dev container! The remote server allows Visual Studio Code to run extensions remotely, such that almost all functionality works just like it does in your local environment.

Your files are volume-mounted into the container so you can open files, and start editing code and get IntelliSense and auto-completions:

You can start debugging, set breakpoints and step through code:

You can run cells and view graphical output in the Python Interactive window:

… and when you open the terminal you are using the terminal inside of the container!

Instead of creating and using dev container definitions, you can also attach Visual Studio Code to any running docker container with the Docker extension and right->clicking on a container and selecting Attach Visual Studio Code:

Attaching visual studio code to a container, using the Docker extension

When attaching to an existing container you may be missing some dependencies used by Visual Studio Code, so if you run into issues check our sample container definitions in our vscode-dev-containers repo for dependencies to add to your Dockerfile.

If you want to get back to the normal local view, you can run the Remote-Containers: Reopen Folder Locally command. All your changes are saved to your workspace via a volume mounted drive and so will be available in the local view.

Remote SSH Workspaces

Another common setup Python developers have is that their development environment is running on a remote machine, often because the remote machine has access to resources or data sets that are not available on the local machine. Like the docker scenario, you can use the “Remote-SSH” extension to open a remote workspace over an SSH connection.

To get started, first ensure that you can ssh to the remote machine from the command line, and then run Remote-SSH: New Window and enter the SSH host you wish to target:

If you configure SSH hosts, they will be readily available in the Remote SSH activity bar for easy connection:

Visual Studio Code will re-open and then install the remote server on the SSH host. You can then open a folder on the remote machine:

… and you can then get started editing and debugging code right away! In this case, none of your source code needs to be local for this to work, all the editing and debugging capabilities are provided by the remote server.

Remote WSL Workspaces

The Windows Subsystem for Linux allows you to run a native Linux bash shell running in windows, similarly to other scenarios. The “Remote-WSL” extension allows the Visual Studio Code UI to run on your windows desktop, while the Visual Studio Code remote server runs extensions inside of the Linux subsystem.

To get started with Remote WSL, run the Remote-WSL: New Window command:

It will then install the Visual Studio Code remote server and give you a new Visual Studio Code window running in a WSL context.

You can click on Open folder… and it will allow you to open a folder in the Linux file system:

Alternatively, you can open a folder in WSL directly by from the wsl prompt by typing “code-insiders .”.

You can then create files, edit code, open a WSL terminal, and debug just like the other remote development environments:

Get Started Now

We are excited for the capabilities this unlocks in Visual Studio Code for Python developers, to get started head over to the Visual Studio Code Remote docs, and/or try out some of our sample apps:

Be sure to let us know of any issues or feedback on the remote extensions by filing issues on our vscode-remote-release GitHub page.


Discussion is closed. Login to edit/delete existing comments.

  • Harry Tyldesley 0

    @Dan Taylor Thanks to you and your team for this! This integration with WSL will enhance both WSL and VSCode for me.  On a general note, the windows linux support gets better and better and it makes windows itself a much more attractive OS for me – and I imagine for many devs. However I wonder, do you have any idea when it will be released in the standard VSCode? I’m not sure I want to be on the cutting edge with a tool I’ll be using for dev daily 😉

    • Dan TaylorMicrosoft employee 0

      It will be available in the stable build in the coming weeks, the insider’s bits are become the stable release about once/month. The quality on insider’s is pretty high though, the VS Code team uses it themselves to develop VS Code!

      • Harry Tyldesley 0

        Great – always reassuring to read when teams take their own medicine 🙂  And I see that its a side by side install too.  The logo colour switch is a nice touch.  I’m now an ‘insider’ 😉  

  • Asaf Horvitz 0

    When will there be suppport in alpine  ?

  • Sean McLeod 0

    Will this also be added to Visual Studio’s python support?

  • keypetro 0

    Thank you for developing this great tool. I really appreciate it. I installed vscode insiders with additional remote development extension and the docker extension tool. Then thanks to your development, I can now attach the docker container to the shell on vscode terminal window, where I can find the contents, the source code and data, in the container. However, although “Attach Visual Studio Code” with the right click on a container creates another window and it actually shows “Attached Continaer …” to my containerat the green, left-bottom bar on the window, I cannot find the contents in the container as did in the shell.
    I would like to modify inside the contianer from the vscode helpful editor just as I editing from the terminal now. How can I get inside or mount the container from vscode window with allowing to access to the contents of the container?
    It seems that your development reflects this hope and will help my coding.
    Thank you very much in advance.

  • Arjun Kirpal 0

    Thank you Dan for your great work. Its great that Microsoft is doing so much in Python.

  • Nathaniel Kenschaft 0

    I have a question about this for use with my school. To access my school’s remote machines, there is a middle layer that you have to pass through, requiring two separate ssh commands to reach the usable machine on the other end. Is there a way to configure this extension for use with that?

  • Hamdi Zrari 0


    Thank you for you detailed Post.

    I am trying to setup and advanced configuration with VScode insider and I ma facing an issue.
    My setup is:

    1. VSCode Running in my local machine Windows 10 with a Django source code hosted on my machine. I have no docker client on this machine, and I don’t wont to install one…
    2. A virtual machine with Ubuntu is running a docker daemon, docker client and docker-compose. My workspace is shared over vboxfs and mounted on my Ubuntu
    3. A python docker container is running in the Ubuntu machine and running the mounted code.

    I tried to use the Remote Extension to debug the python code inside the container. However, when a run my vscode inside on the remote SSH Taget (so the ubuntu machine), I am able to manage docker objects (images, containers, etc…) using the Docker extension of vscode, but I can’t see the option: Remote-Containers: Open Folder in Container. It’s not found in the F1 command… I can see the other related command like: Remote-Containers: Settings.

    Do you have any idea ? Or my setup is not supported by the extension ? It seems like it supports SSH development or Container development but not mixing both together, right ?


    • rahul verma 0

      Facing the exact same issue, in the exact same setup.
      Though what I figured out was – you don’t need to connect using Remote-ssh extension, because once you do so, remote-containers extension is not available (as you rightly said).

      I am waiting for any answer on this. I tried ssh tunneling also, which connects through Docker extension, but not through remote-containers.

  • Rex Barker 0

    Nice post. In my case, I’m looking for a combination of your techniques. I’m trying to debug into a running docker container, on a remote machine (via SSH). I have all of the VS code extensions, as far as I can tell. But I still cannot connect a VS code debug session to the running remote container. On my local machine, the docker extension looks through local containers (local: macOS laptop). The VS code “Remote SSH” extension does not show the remote containers. What I would like to do looks like this:

    local laptop (macOS) —> SSH to remote —> Remote host (Ubutnu) —> Docker container

    So far, I can get remote SSH to work, docker local to work, but not remote SSH–>docker to work

    • Kevin Lin 0

      I’m trying to figure this out too. I’ve found this, which recommends using VSCode Remote Containers, but setting the Docker Host to the remote machine.

      Seems like there’s some limitations with file syncing though.

      • Ayush Mehta 0

        Tried this. Still remote containers not showing up through remote-containers or remote-ssh extension.
        Installed the docker extension, and the remote containers became visible, but only a shell can be attached to the containers on the host machine, it gives an error on attaching vs-code to any container.
        Any ideas how to proceed?

Feedback usabilla icon