How to Use GitHub Codespaces in VS Code

You use GitHub Codespaces in VS Code by installing the Codespaces extension, authorizing GitHub, and creating or opening a codespace from the Remote Explorer. A codespace is a cloud-hosted development environment associated with a repository and branch.

The environment runs on GitHub's infrastructure. You connect to it from VS Code desktop or a browser, and you get the full editor experience: IntelliSense, terminal, debugging, and extensions.

What you need

Install the GitHub Codespaces extension, published by GitHub with ID GitHub.codespaces. You also need a GitHub account and permission to create a codespace for the selected repository.

Personal GitHub Free and Pro accounts currently include monthly compute and storage quotas. Check the current Codespaces billing documentation and the payer shown during creation. Repository and organization policies can restrict availability and machine types.

If the repository contains a devcontainer.json, review its image, Features, mounts, secrets, and lifecycle commands before creation. Codespaces uses a default Linux image when no configuration is supplied.

Step 1: Sign in to GitHub from VS Code

Open the Remote Explorer from the Activity Bar. At the top of the Remote Explorer, open the dropdown and select GitHub Codespaces. Click Sign in to GitHub and follow the browser prompts to authorize VS Code.

Once signed in, the Remote Explorer shows your existing codespaces and gives you the option to create new ones.

Step 2: Create a new codespace

In the Remote Explorer, click the plus icon or run Codespaces: Create New Codespace from the Command Palette. Type the name of the GitHub repository you want to work on and select it from the list.

Next, choose the branch. If the repository has multiple dev container configurations, select the intended one. Finally, choose from the machine types permitted for that repository and account.

The available range can be limited by repository requirements or organization policy. Machine types use different compute multipliers and billing tiers, so start with the lowest valid option that can run the project.

VS Code connects to the new codespace and sets up the environment. The first launch takes a few minutes while the container builds. Subsequent opens are faster.

Step 3: Work inside the codespace

Once connected, the Status Bar shows Codespaces: repository-name. You are now working in a cloud environment.

The repository, terminal, language tools, and debugger run in the codespace. The editor UI runs in local VS Code, and VS Code places extensions on the local UI or remote codespace according to their requirements.

The repository is cloned into the codespace. Codespaces processes supported extensions, ports, environment settings, and lifecycle commands declared by the selected dev container configuration. Required secrets must be supplied through Codespaces secrets rather than committed to the repository.

Step 4: Change the machine type

If you need more CPU or RAM, you can change the machine type without creating a new codespace. Open the Command Palette and run Codespaces: Change Machine Type. Pick a different tier from the list.

If the new machine type has a different storage capacity, the codespace stops while the change is applied. You can restart it when the process completes. If the storage capacity is the same, the change takes effect the next time you restart the codespace.

Step 5: Open an existing codespace

To return to a codespace you created earlier, open the Remote Explorer, select GitHub Codespaces from the dropdown, and click the connection icon next to the codespace name. VS Code reconnects and restores your workspace.

You can also browse your codespaces on github.com/codespaces and open any of them in VS Code desktop or the browser.

Codespaces in a browser versus github.dev

A browser-based codespace connects to the same cloud compute environment and supports terminals and server-side tools. Open an existing environment from github.com/codespaces, or choose the browser option when creating one on GitHub.

Pressing the period key on a repository page or changing github.com to github.dev opens the free, lightweight web editor instead. That editor is not a codespace and has no cloud runtime, terminal, or debugger.

Managing and deleting codespaces

Closing the VS Code window does not stop the codespace. Run Codespaces: Stop Codespace and select the environment, or stop it from github.com/codespaces. A stopped codespace does not consume compute usage, but it continues to consume storage.

Before deletion, commit and push repository work, and copy out any untracked files or other data you need. Then, while you are not connected to that codespace, right-click it in the Remote Explorer and select Delete Codespace. Deletion permanently removes the environment and its remaining storage.

Troubleshooting

Codespace creation fails or times out. Check GitHub Status, then open the streamed build log. When connected to a failed or recovery environment, run Codespaces: View Creation Log to inspect the container configuration and non-interactive setup commands before retrying.

Extensions do not install. Verify that the extension IDs in devcontainer.json are correct. Some extensions do not work in the browser-based editor. Open the codespace in VS Code desktop for full extension support.

Port forwarding does not work in the browser. In browser-based Codespaces, manually visiting localhost:forwarded_port does not work. Click the link from the port forwarding notification or the globe icon in the Ports view to open your app with the correct URL.

Next, learn how to forward ports for local and remote development to share services running in your codespace, or open a GitHub repository without cloning for quick browsing.