Check Out a GitHub Pull Request with gh pr checkout

gh pr checkout pulls a colleague's pull request straight into your local clone to run or read. The examples use GitHub CLI 2.87.3, installed here as package version 2.45.0-1ubuntu0.3+esm3. Budget about ten minutes for a clean working tree and a pull request that already exists on GitHub.

• You need: gh, Git, an authenticated GitHub CLI session, and a local clone of the repository.
• What it touches: the current repository's working tree and branch. It does not merge the pull request.
• Privileges: none, normally. Do not run it with sudo: root-owned files created by a later build step are a pain to clean up.

1. Check the installed command and repository

Start with read-only checks, run from the local clone that contains the pull request's base repository:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ git rev-parse --show-toplevel
/home/you/src/example
$ gh auth status
github.com
  Logged in to github.com account YOUR_ACCOUNT

The account line varies. If gh auth status reports that you are not logged in, authenticate through your normal organisation-approved process before continuing. An authenticated account still needs permission to read the repository and pull request.

2. Protect uncommitted work

Before checkout, inspect the worktree:

$ git status --short

No output means there are no tracked or untracked changes for Git to report. That is the simplest state for switching branches. If you see work that you need, stop and either commit it on a suitable branch or save it with a deliberate stash:

$ git switch -c work-before-pr
$ git add path/to/your-file
$ git commit -m 'WIP: save local changes'

Do not blindly run git clean -fd or discard changes to make checkout convenient: that removes untracked files permanently. If you used a new WIP branch, return to it later with git switch work-before-pr.

3. Check out a specific pull request

Use its number when you are already in the correct repository:

$ gh pr checkout 123
From https://github.com/OWNER/REPOSITORY
Switched to branch 'fix-example'

The branch name and fetch output depend on the pull request. The command resolves the pull request, fetches its head, and creates or updates a local branch. Pass the full pull request URL instead to remove any ambiguity:

$ gh pr checkout https://github.com/OWNER/REPOSITORY/pull/123

For a repository other than the current one, select it explicitly with --repo:

$ gh pr checkout 123 --repo OWNER/REPOSITORY

After either form, verify what Git actually selected:

$ git status --short --branch
## fix-example
$ gh pr view --json number,title,headRefName,baseRefName
{
  "number": 123,
  "title": "Example fix",
  "headRefName": "fix-example",
  "baseRefName": "main"
}

The JSON values above are examples, not fixed output. What matters is that the number, title and head branch match the change you meant to inspect.

4. Choose a safe local branch name

By default, the local branch takes the pull request's head branch name. That gets confusing fast when you already have a branch with that name, or you are comparing several pull requests side by side. Give it a distinct local name with --branch:

$ gh pr checkout 123 --branch review-pr-123
$ git branch --show-current
review-pr-123

This changes only the local name. Keep the pull request number in it when you expect to review more than one candidate: it makes cleanup easier to audit later.

5. Use detached HEAD for a throwaway inspection

If you only need to build or read the pull request and do not want a local branch, use --detach:

$ gh pr checkout 123 --detach
$ git status --short --branch
## HEAD (no branch)
$ git log -1 --oneline
abc1234 Example fix

A detached HEAD is easy to leave accidentally. Before making any commits, switch to a named branch or create one:

$ git switch -c review-pr-123-notes

When the inspection is over, return to your previous branch by name, for example git switch main. If a disposable branch turned out to hold nothing useful, remove it with git branch -d review-pr-123-notes. Git refuses if that branch has unmerged commits; do not swap -d for -D unless you have checked the commits and accept irreversible local loss.

6. Know what force and submodules actually do

--force is the dangerous option in this command: it resets an existing local branch to the latest state of the pull request. Treat it as destructive.

• Record the branch first. Inspect its commits before you touch anything.

  $ git branch --show-current
  review-pr-123
  $ git log --oneline --decorate -5
  

• Back it up before forcing. Make a backup reference if the branch might hold work you need.

  $ git branch backup/review-pr-123-before-force
  $ gh pr checkout 123 --branch review-pr-123 --force
  

• Recover from the backup if needed. Switch away from the target branch and check the backup's commits before you reset or recreate anything.

  $ git switch backup/review-pr-123-before-force
  $ git log --oneline -5
  

Use --recurse-submodules only when the repository's test or build genuinely needs its submodules updated. It changes nested repositories as part of checkout and may fetch more data. Check the result with git submodule status, and do not assume a submodule update is harmless in a worktree that has local edits inside a submodule.

7. Diagnose the common failures

• Pull request number rejected. Confirm the repository and number with gh pr view 123 --repo OWNER/REPOSITORY.
• Access fails. Check gh auth status and your repository permissions.
• Checkout refuses because local changes would be overwritten. Go back to step 2, save or commit the work. Do not fix this by deleting files.
• Branch already exists. Decide whether it is the one you want: use a new name with --branch for an independent review, or --force only after a backup, accepting the target branch will be reset.
• Fetch or checkout interrupted. Inspect git status and git branch --show-current before retrying.

The installed 2.87.3 command advertises the options documented above: --branch, --detach, --force, --recurse-submodules, and the inherited --repo. Check gh pr checkout --help on another machine before copying this guide there, because GitHub CLI versions can add options or change their help text.