Rebuild a GitHub Codespace Without Losing Work

gh codespace rebuild recreates a Codespace from the dev container in its working directory, keeping the code and current changes intact. Allow about five minutes for the command and the remote rebuild, longer if the container image itself has to rebuild from scratch.

This touches a remote development environment, not a local Docker restart, and it can interrupt your editor session, running processes and forwarded services. Read the target name and the rebuild mode before you press Enter. The examples use the installed GitHub CLI 2.87.3.

1. Confirm the installed command

Check that the expected GitHub CLI is on your path and that this subcommand exposes what this guide describes:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh codespace rebuild --help
Rebuilding recreates your codespace.

USAGE
  gh codespace rebuild [flags]

Version and help formatting may differ elsewhere. The installed manual documents four useful selectors: --codespace, --repo, --repo-owner, and the choice of --full.

Checkpoint: if gh codespace rebuild --help does not show the command, stop and check the GitHub CLI installation before trying a repair command copied from elsewhere.

2. Identify the target before rebuilding

Use the exact codespace name when you know it: a name is safer than an interactive choice, especially with several codespaces open at once:

$ gh codespace rebuild --codespace CODESPACE_NAME

Swap in the real name, no angle brackets, no invented repository name. To narrow by repository instead, use its OWNER/REPOSITORY form:

$ gh codespace rebuild --repo OWNER/REPOSITORY
$ gh codespace rebuild --repo-owner OWNER --repo OWNER/REPOSITORY

Repository and owner options are filters, not a substitute for a valid login, repository access or a running codespace. If a filter can still match more than one target, fall back to --codespace with the exact name. Never paste an access token into any of these arguments; GitHub CLI handles authentication on its own.

3. Save the work you cannot afford to interrupt

The rebuild documentation says code and current changes are preserved, but that is not a backup, and it does not protect work outside the codespace or data held only by a running process. Commit or otherwise copy anything irreplaceable first:

$ git status --short
$ git diff --check
$ git log -1 --oneline

None of these checks modify the repository. A clean git diff --check means Git found no whitespace errors in the current diff, not that every change is committed. Generated files, local databases and untracked notes need their own plan, since the rebuild's preservation guarantee covers code and current changes, not every process-managed data store. There is no elevated-privilege step here: GitHub CLI credentials and the remote codespace belong to your user account, so leave sudo out of it.

4. Run an ordinary rebuild first

A normal rebuild recreates the codespace from the dev container in its working directory:

$ gh codespace rebuild --codespace CODESPACE_NAME

GitHub CLI may print progress or an error from the service; the useful local signal is the exit status:

$ printf 'rebuild command status: %s\n' "$?"
rebuild command status: 0

Status 0 means the command completed, not that your application is healthy or that every extension and service has reconnected. Reopen the codespace in your editor, wait for the container to settle, then check the project with its own test or status command. Expect disruption while the rebuild runs: stop any long-running task first and tell collaborators if the codespace hosts a shared preview. If the command fails, keep the error text and inspect the codespace state through your usual GitHub or editor view before repeating it.

5. Use a full rebuild only for a cache problem

Add --full only when you have a reason to clear cached Docker images as part of the rebuild:

$ gh codespace rebuild --codespace CODESPACE_NAME --full

A full rebuild still preserves code and current changes, but it removes cached Docker images, so it can run slower while layers download or build again. It does not mean 'delete the codespace', and it is not a general fix for a broken application, bad credentials or a failing test.

Warning: a full rebuild changes the cache state and can burn through network bandwidth and build time. Do not reach for it just because the normal rebuild feels slow: capture the actual failing error first, then choose the smallest intervention that addresses it.

6. Check the result and recover safely

Once the codespace reconnects, return to the project and verify the files and changes you expected:

$ git status --short
$ git diff --stat
$ git diff --check

Run the project's own normal test or startup command next; this guide cannot invent one, since it depends on the repository. Check that ports, terminals, extensions and environment-backed services have all returned.

A rebuild has no local undo command. A dev container configuration problem gets fixed by editing the repository's configuration and rebuilding again after reviewing the change. If something important is missing, stop making further changes and check the repository history, any untracked-file backup, and whatever remote branch or external backup your team relies on. Repeating a full rebuild will not recover data that was never committed or copied elsewhere.

Done means