Command referencegh pr checkout
gh pr checkout command (Linux & Windows / GitHub CLI)
What it does
Check out a pull request locally as a branch so you can build, test, or review the changes. When people search for gh pr checkout, they usually want practical GitHub CLI flags, safe examples, and how this subcommand fits everyday PR and repo workflows on Linux, Windows, and macOS. Syntax, options, and copyable examples are below.
Check out a pull request locally as a branch so you can build, test, or review the changes.
Syntax
gh pr checkout {<number> | <url> | <branch>} [flags]Common options
| Flag / option | Meaning |
|---|---|
| number | Pull request number. |
| --recurse-submodules | Update submodules after checkout when needed. |
| --detach | Check out in detached HEAD state. |
| --force | Reset the local branch to match the pull request tip. |
Practical examples
Checkout by number
gh pr checkout 123
Fetches the PR head and switches to a local branch for it.
From URL
gh pr checkout https://github.com/OWNER/REPO/pull/123
Works from a copied pull request URL.
Force refresh
gh pr checkout 123 --force
Resets the local PR branch to the latest remote head.
Common mistakes
- Checking out with uncommitted local changes that conflict.
- Reviewing on a stale local branch without `--force` or a fresh fetch.
Related commands
- gh pr listList pull requests in a repository with state, author, and search filters.
- gh pr diffShow the diff for a pull request in the terminal.
- gh pr reviewSubmit an approve, request-changes, or comment review on a pull request.
- gh pr viewDisplay pull request metadata, body, and checks in the terminal or browser.
- gh auth loginAuthenticate the GitHub CLI with GitHub.com or GitHub Enterprise so other gh commands can run.
- gh pr createCreate a pull request from the current branch with title, body, reviewers, and base branch options.
- gh pr mergeMerge a pull request using merge commit, squash, or rebase strategies.
- gitTrack source history and collaborate through distributed repositories.
FAQ
What does gh pr checkout do in GitHub CLI?
Check out a pull request locally as a branch so you can build, test, or review the changes.
Does gh pr checkout work on Windows and Linux?
Yes. The GitHub CLI (`gh`) runs on Linux, Windows, and macOS with the same subcommand syntax after you authenticate with `gh auth login`.
What is a practical gh pr checkout example?
Try `gh pr checkout 123` — Fetches the PR head and switches to a local branch for it.
Do I need a token in the command line for gh pr checkout?
Prefer `gh auth login` so credentials stay in the system keyring or secure storage. Avoid pasting personal access tokens into shell history.
Browse the full Linux and Windows command reference to search more bash, CMD, PowerShell, Conda, and GitHub CLI commands.