Configuring Codespaces for your project

You can set up a default configuration for every new codespace for your repository to ensure that contributors have all the tools and settings they need in their online development environment.

People with write permissions to a repository can create or edit the default codespace configuration.

Codespaces is available for user accounts using GitHub Free or GitHub Pro. For more information, see "GitHub's products."

In this article

Note: Codespaces is currently in limited public beta and subject to change. During the beta period, GitHub does not make any guarantees about the availability of Codespaces. For more information about joining the beta, see "About Codespaces."

About default codespace configurations

You can create a default codespace configuration for your repository that determines the environment of every new codespace anyone creates for that repository. The configuration defines a development container that can include frameworks, tools, extensions, and port forwarding.

If you don't define a configuration in your repository, GitHub creates a codespace with a base Linux image. The base Linux image includes tools for Python, Node.js, JavaScript, TypeScript, C++, Java, C#, F#, .NET Core, PHP, PowerShell, Go, Ruby, and Rust. For more information about the base Linux image, see the microsoft/vscode-dev-containers repository.

You can also personalize aspects of the codespace environment for any codespace that your account creates. Personalization can include shell preferences and additional tools. Your dotfiles personalization is applied before a repository's default codespace configuration. For more information, see "Personalizing Codespaces for your account."

You can create a default codespace configuration using a pre-built container configuration for your project type, or you can create a custom configuration specific to your project's needs.

Codespaces uses settings contained in a configuration file named devcontainer.json. This file can be located in the root of the repository or in a folder called .devcontainer. If the file is located in the root of the repository, the filename must begin with a period: .devcontainer.json.

Each new codespace created from a branch that contains the .devcontainer folder will be configured according to the folder's contents. For more information, see "Creating a codespace."

You can use your devcontainer.json to set default settings for the entire codespace environment, including the Visual Studio Code editor, but you can also set editor-specific settings in a file named .vscode/settings.json.

Using a pre-built container configuration

Pre-built container definitions include a common configuration for a particular project type, and can help you quickly get started with a configuration that already has the appropriate container options, Visual Studio Code settings, and Visual Studio Code extensions that should be installed.

  1. Access the command palette (shift command P / shift control P), then start typing "Codespaces: Add Development Container Configuration Files...". Click Codespaces: Add Development Container Configuration Files... "Codespaces: Add Development Container Configuration Files..." in the command palette
  2. Click the definition you want to use. List of predefined container definitions
  3. Follow the prompts to customize your definition.
  4. Click OK. OK button
  5. To apply the changes, in the bottom right corner of the screen, click Rebuild now. For more information about rebuilding your container, see "Applying changes to your configuration." "Codespaces: Rebuild Container" in the command palette

Creating a custom codespace configuration

If none of the pre-built configurations meet your needs, you can create a custom configuration by adding a devcontainer.json file. This file can be located in the root of the repository or in a folder called .devcontainer. If the file is located in the root of the repository, the filename must begin with a period: .devcontainer.json.

In the file, you can use supported configuration keys to specify aspects of the codespace's environment, like which Visual Studio Code extensions will be installed.

When you configure editor settings for Visual Studio Code, there are three scopes available: Workspace, Remote [Codespaces], and User. If a setting is defined in multiple scopes, Workspace settings take priority, then Remote [Codespaces], then User.

You can define default editor settings for Visual Studio Code in two places.

  • Editor settings defined in .vscode/settings.json are applied as Workspace-scoped settings in the codespace.
  • Editor settings defined in the settings key in devcontainer.json are applied as Remote [Codespaces]-scoped settings in the codespace.

After updating the devcontainer.json file, you can rebuild the container for your codespace to apply the changes. For more information, see "Applying changes to your configuration."

Supported codespace configuration keys

You can use configuration keys supported by Codespaces in devcontainer.json.

General settings

  • name
  • settings
  • extensions
  • forwardPorts
  • postCreateCommand

Docker, Dockerfile, or image settings

  • image
  • dockerFile
  • context
  • containerEnv
  • remoteEnv
  • containerUser
  • remoteUser
  • mounts
  • runArgs
  • overrideCommand
  • dockerComposeFile

For more information about the available settings for devcontainer.json, see devcontainer.json reference in the Visual Studio Code documentation.

Applying changes to your configuration

After the Codespaces configuration for a repository changes, you can apply the changes to an existing codespace by rebuilding the container for the codespace.

  1. Access the command palette (shift command P / shift control P), then start typing "Codespaces: Rebuild Container". Click Codespaces: Rebuild Container. "Codespaces: Rebuild Container" in the command palette
  2. If changes to your codespace's configuration cause a container error, your codespace will run in recovery mode, and you will see an error message. Fix the errors in the configuration. Error message about recovery mode
    • To diagnose the error by reviewing the creation logs, click View creation log.
    • To fix the errors identified in the logs, update your devcontainer.json file.
    • To apply the changes, rebuild your container. Access the command palette (shift command P / shift control P), then start typing "Codespaces: Rebuild Container". Click Codespaces: Rebuild Container.

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.