gh pr checkout

Switch to any PR branch, including forks

gh pr checkout fetches a pull request's branch and switches to it locally — even when the PR comes from someone else's fork, which is painful to do with raw git. Pass a PR number, URL, or branch name and gh handles the remote, fetch, and checkout for you.

Quick answer

gh pr checkout 123

↧ Download snippet Full cheat sheet

Syntax

gh pr checkout {<number> | <url> | <branch>} [flags]

Examples

Check out PR #123 by number

gh pr checkout 123

Check out by full URL

gh pr checkout https://github.com/cli/cli/pull/123

Check out into a differently named local branch

gh pr checkout 123 --branch review-123

Update submodules while checking out

gh pr checkout 123 --recurse-submodules

Detach HEAD instead of creating a branch

gh pr checkout 123 --detach

Options & flags

Flag	What it does
-b, --branch	Local branch name to use instead of the PR's head branch name.
--detach	Check out the PR in detached HEAD state.
-f, --force	Reset the existing local branch to the latest state of the PR.
--recurse-submodules	Update all submodules after checkout.

How to use gh pr checkout, step by step

Find the PR number with gh pr list or from the PR page.
Run gh pr checkout 123 inside the repository.
gh adds the fork remote if needed, fetches the branch, and switches to it.
Review, test, or push follow-up commits — for maintainer-editable PRs your pushes go back to the contributor's branch.

Common errors and fixes

could not find any commits between ... failed to run git: fatal: couldn't find remote ref

The contributor may have deleted their branch, or the PR is closed. Confirm it is still open with gh pr view 123.

local changes would be overwritten by checkout

Commit or stash your work first: git stash, run the checkout, then git stash pop. Or use --force to reset the branch.

Related commands

Frequently asked questions

How do I check out a pull request from a fork?

gh pr checkout handles forks automatically. Run gh pr checkout <number> and gh adds the contributor's fork as a remote, fetches the branch, and switches to it — no manual git remote wrangling.

Can I rename the local branch when I check out a PR?

Yes, use --branch: gh pr checkout 123 --branch review-123 checks the PR out into a local branch called review-123.

How do I update a PR I checked out?

Re-run gh pr checkout 123 to fast-forward, or add --force to hard-reset your local branch to the PR's latest state.