 |
Visual Studio Code Remote Development and GitHub Codespaces Open your code in the cloud, in a local container, on a remote machine, or in WSL and take advantage of VS Code's full feature set. |
A development container is a running Docker container with a well-defined tool/runtime stack and its prerequisites. The VS Code Remote - Containers extension allows you to clone a repository or open any folder mounted into (or already inside) a dev container and take advantage of VS Code's full development feature set. GitHub Codespaces both use this same concept to quickly create customized, cloud-based development environments accessible from VS Code or the web.
This repository contains a set of dev container definitions to help get you up and running with a containerized environment. The definitions describe the appropriate container image, runtime arguments for starting the container, and VS Code extensions that should be installed. Each provides a container configuration file (devcontainer.json) and other needed files that you can drop into any existing folder as a starting point for containerizing your project.
Note: While many of these definitions are also expected to work in GitHub Codespaces, a few are not yet working. See here for a list of known issues.
The vscode-remote-try-* repositories may also be of interest if you are looking for complete sample projects.
To add a dev container definition in your project, you can either:
Manually add it to your project folder:
- Clone this repository.
- Copy the contents of the
.devcontainerfolder from of one of the definitions in thecontainersfolder to your project folder. - See the definition's
READMEfor configuration details and options. - Open the folder locally with the Remote - Containers extension or commit the file to source control to use it with Codespaces.
... or ...
Add it using VS Code Remote - Containers:
- Set up your machine and then start VS Code and open your project folder.
- Press F1, select the Remote-Containers: Add Development Container Configuration Files... command, and pick one of definitions from the list. (You may need to choose the From a predefined container configuration definition... option if your project has an existing Dockerfile or Docker Compose file.)
- See the definition's
READMEfor configuration options. A link is available in the.devcontainer/devcontainer.jsonfile added to your folder. - Run Remote-Containers: Reopen in Container to use it locally, or commit the file to source control to use it with Codespaces.
You can share a customized dev container definition for your project by adding the files under .devcontainer to source control.
Anyone who then opens a local copy of your repo in VS Code will be prompted to reopen the folder in a container, provided they have the Remote - Containers extension installed.
Additionally, if you reference your Git repository when creating a codespace GitHub Codespaces, the container definition will be used.
Your team now has a consistent environment and tool-chain and new contributors or team members can be productive quickly. First-time contributors will require less guidance and there will be fewer issues related to environment setup.
If you want to try a sample project which already has a dev container, check out one of the following repositories:
containers- Contains reusable dev container definitions.script-library- Includes scripts used in this repository to install things. Also useful in your own Dockerfiles.repository-containers- Dev container definitions for working public source code repositories.container-templates- Contains templates for creating your own container definitions or to contribute back.
Yes, if you want to use an existing Dockerfile as a starting point, use the Remote - Containers extension, open a folder, and then run Remote-Containers: Add Development Container Configuration Files... from the Command Palette (F1). You'll be prompted to select a Dockerfile or Docker Compose file and customize from there. If you then commit these files to a Git repository, you can use it with GitHub Codespaces as well. If you prefer, you can also start up the container manually and attach to it.
A devcontainer.json file is similar to launch.json for debugging, but designed to launch (or attach to) a development container instead. At its simplest, all you need is a .devcontainer/devcontainer.json file in your project that references an image, Dockerfile, or docker-compose.yml, and a few properties. You can adapt it for use in a wide variety of situations.
Each RUN statement creates a Docker image "layer". If one RUN statement adds temporary contents, these contents remain in this layer in the image even if they are deleted in a subsequent RUN. This means the image takes more storage locally and results in slower image download times if you publish the image to a registry. You can resolve this problem by using a RUN statement that includes any clean up steps (separated by &&) after a given operation. See CONTRIBUTING.md for more tips.
Have a question or feedback?
- Contribute or provide feedback for the VS Code Remote extensions or GitHub Codespaces.
- Search existing issues with dev container definitions or report a problem.
- Contribute a development container definition to the repository.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under the MIT License. See LICENSE.
For images generated from this repository, see LICENSE and NOTICE.txt.