The Complete, Step‑by‑Step Guide to Installing GitHub CLI (gh) on Any Operating System

1. What is GitHub CLI?

2. Prerequisites (the same everywhere)

Tip: Verify you have Git already:

git --version
# e.g. git version 2.44.0

If not, install Git first (most OS package managers have a git package).

3. Installing on Windows

3.1 Preferred: winget (the Windows Package Manager)

Winget ships with Windows 10 22H2 and later, and with Windows 11.

# Open PowerShell (run as normal user – no admin needed)
winget install --id GitHub.cli --source winget

What happens?

• Winget downloads the latest .msi from the official GitHub releases.
• The installer adds gh.exe to %USERPROFILE%\AppData\Local\Microsoft\WindowsApps (which is already in your PATH).

Verify

gh --version
# gh version 2.45.0 (2025‑11‑23)

3.2 Alternative 1: Scoop (community‑driven)

# First install Scoop (if you don’t have it)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
iwr -useb get.scoop.sh | iex

# Then install gh
scoop install gh

Why Scoop? It installs everything under %USERPROFILE%\scoop\apps, keeping your system “clean” (no admin rights needed).

Verify

gh --version

3.3 Alternative 2: Chocolatey

# (Run PowerShell as Administrator)
choco install gh

3.4 Manual binary (works on any Windows, even without a package manager)

1. Download the latest Windows archive from the official releases page:https://github.com/cli/cli/releases/latest → look for gh_2.45.0_windows_amd64.zip (or arm64 for ARM PCs).
2. Extract the zip to a folder of your choice, e.g. C:\Tools\gh.
3. Add the folder to your PATH:
   • Press Win + X → System → Advanced system settings → Environment Variables.
   • Under User variables click Path → Edit → New and paste C:\Tools\gh.

Open a new terminal and run:

gh --version

3.5 Post‑install: Authenticate gh

gh auth login
# Follow the interactive prompts:
#   • Choose GitHub.com
#   • Choose HTTPS or SSH (HTTPS is simplest)
#   • Login with a web browser (recommended) or paste a token

After login you can test:

gh repo view cli/cli

3.6 Upgrade & Uninstall (Windows)

4. Installing on macOS

4.1 Preferred: Homebrew

If you already have Homebrew (brew), run:

brew install gh

What Homebrew does

• Installs the latest gh formula (currently a pre‑compiled binary).
• Puts gh into /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel) – both are already in your $PATH.

Verify

gh --version

4.2 Alternative 1: MacPorts

sudo port install gh

4.3 Alternative 2: Manual binary

1. Download gh_2.45.0_macOS_amd64.tar.gz (or arm64 for Apple Silicon) from the releases page.

Reload the shell or source ~/.zshrc and check:

gh --version

Add to PATH (add this line to ~/.zshrc or ~/.bash_profile):

export PATH="$HOME/opt/gh/bin:$PATH"

Extract to a location of your choice, e.g. ~/opt/gh:

mkdir -p ~/opt/gh
tar -xzf gh_2.45.0_macOS_amd64.tar.gz -C ~/opt/gh --strip-components=1

4.4 Post‑install: Authenticate (macOS)

gh auth login

Same interactive flow as on Windows.

Optional – enable shell completions (Homebrew already does this, but for manual installs you need to run once):

# Bash
gh completion -s bash > ~/.gh_completion
echo 'source ~/.gh_completion' >> ~/.bashrc

# Zsh
gh completion -s zsh > "${fpath[1]}/_gh"
# Fish
gh completion -s fish > ~/.config/fish/completions/gh.fish

4.5 Upgrade & Uninstall (macOS)

5. Installing on Linux

Because Linux comes in many flavors, we list the most common distro families and a universal “download‑and‑run” option that works on any Linux with glibc 2.28+ (or the static build for older systems).

5.1 Debian / Ubuntu / Linux Mint (APT)

# 1️⃣ Add the official GitHub CLI apt repository
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
   | sudo gpg --dearmor -o /usr/share/keyrings/githubcli-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages $(lsb_release -cs) main" \
   | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null

# 2️⃣ Update apt cache and install
sudo apt update
sudo apt install gh

Latest Ubuntu user? Just try to install the gh package from apt with sudo apt install gh.

Verify

gh --version

Upgrade

sudo apt update && sudo apt upgrade gh

Uninstall

sudo apt purge gh

5.2 Fedora / RHEL / CentOS / AlmaLinux (DNF)

sudo dnf install 'dnf-command(config-manager)'
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh

Upgrade

sudo dnf upgrade gh

Uninstall

sudo dnf remove gh

5.3 openSUSE (Zypper)

sudo zypper ar https://cli.github.com/packages/rpm/gh-cli.repo gh-cli
sudo zypper install gh

5.4 Arch Linux / Manjaro (Pacman)

gh is in the extra repository, so:

sudo pacman -S gh

If you prefer the bleeding‑edge version, use the AUR:

git clone https://aur.archlinux.org/gh-cli.git
cd gh-cli
makepkg -si

5.5 Alpine Linux (apk)

Alpine ships a static binary:

# The repository is community‑maintained, not official yet.
# First enable the community repo if not already:
echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" | \
   sudo tee -a /etc/apk/repositories

sudo apk update
sudo apk add gh

Note: Alpine’s musl C library is compatible with the static build; you won’t see missing‑library errors.

5.6 Any other Linux distribution – Manual binary (tarball)

1. Pick the right tarball from the releases page:
   • gh_2.45.0_linux_amd64.tar.gz for x86‑64
   • gh_2.45.0_linux_arm64.tar.gz for ARM 64 (e.g., Raspberry Pi 4, AWS Graviton)

Verify

gh --version

Extract to /usr/local (system‑wide) or $HOME/.local (user‑only).

# System‑wide (needs sudo)
sudo tar -xzf gh_2.45.0_linux_amd64.tar.gz -C /usr/local --strip-components=1

# User‑only (no sudo)
mkdir -p $HOME/.local/gh
tar -xzf gh_2.45.0_linux_amd64.tar.gz -C $HOME/.local/gh --strip-components=1
echo 'export PATH="$HOME/.local/gh/bin:$PATH"' >> $HOME/.bashrc
source $HOME/.bashrc

5.7 Post‑install: Authenticate

gh auth login

Same prompts as on Windows/macOS.

If you want to use SSH for every remote, you can set it once:

gh auth login --with-token < ~/.ssh/github_token
gh config set git_protocol ssh

5.8 Upgrade & Uninstall (macOS & Linux)

6. Installing on WSL (Windows Subsystem for Linux)

WSL behaves like a normal Linux distribution, so follow the Linux instructions that correspond to the distro you installed (Ubuntu, Debian, Fedora, …).

Extra tip: If you want gh to be available from Windows PowerShell as well, you can expose the Linux binary via the Windows path:

# In PowerShell (as your Windows user)
$Env:PATH += ";\\wsl$\Ubuntu\usr\local\bin"

Now you can call gh directly from PowerShell, and it will forward to the WSL binary.

7. Installing inside Docker / OCI containers

Running gh inside a container is handy for CI pipelines.

7.1 Minimal Dockerfile (uses the official static binary)

# Use a tiny base image (Alpine or Debian‑slim)
FROM alpine:3.20 AS downloader
ARG GH_VERSION=2.45.0
ARG TARGETOS=linux
ARG TARGETARCH=amd64   # change to arm64 for ARM runners

# Download the tarball
ADD https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_${TARGETOS}_${TARGETARCH}.tar.gz /tmp/gh.tar.gz

# Extract
RUN tar -xzf /tmp/gh.tar.gz -C /usr/local/bin --strip-components=1 gh_${GH_VERSION}_${TARGETOS}_${TARGETARCH}/bin/gh

# Final image – you can also start from `scratch` if you want ultra‑small
FROM alpine:3.20
COPY --from=downloader /usr/local/bin/gh /usr/local/bin/gh
ENTRYPOINT ["gh"]

Build and test:

docker build -t gh-cli .
docker run --rm gh-cli version

7.2 Using GitHub Actions (no installation needed)

GitHub’s own runner images already contain gh. In a workflow you can just call it:

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - name: Show gh version
        run: gh --version

8. Installing from Source (for power‑users & developers)

Building from source gives you a custom binary (e.g., compiled with a different GOFLAGS or patched).
The process is the same on every platform because the CLI is written in Go.

8.1 Prerequisites

# Install Go (>=1.22) – use your OS’s package manager or download from golang.org
go version
# go version go1.22.5 linux/amd64

8.2 Clone the repo and build

git clone https://github.com/cli/cli.git
cd cli
# Check out the tag you want (optional)
git checkout v2.45.0

# Build the binary (the `./cmd/gh` package)
make build
# The binary ends up at ./bin/gh

8.3 Install the binary

# System‑wide (needs sudo)
sudo cp ./bin/gh /usr/local/bin/
# Or user‑only
mkdir -p $HOME/.local/bin
cp ./bin/gh $HOME/.local/bin/

Verify gh --version.

Note: When you build from source you must keep the source tree if you ever want to rebuild after a git pull. The binary itself is not auto‑updating.

9. Common Post‑Installation Tasks

10. Troubleshooting

How to see detailed logs

Add the environment variable GH_DEBUG=1 before a command:

GH_DEBUG=1 gh api /user

You’ll get a full dump of request/response data – perfect for filing a bug report.

11. Summary Checklist

12. Quick‑Start Cheat‑Sheet (Copy‑Paste)

Windows (winget)

winget install --id GitHub.cli
gh auth login

macOS (Homebrew)

brew install gh
gh auth login

Ubuntu / Debian

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null

sudo apt update
sudo apt install gh
gh auth login

Fedora

sudo dnf install 'dnf-command(config-manager)'
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf install gh
gh auth login

Arch Linux

sudo pacman -S gh
gh auth login

Any OS – Manual binary (no package manager)

# 1️⃣ Pick the right archive for your platform from:
#    https://github.com/cli/cli/releases/latest
# 2️⃣ Extract it somewhere, add that folder to $PATH,
# 3️⃣ Verify:
gh --version
# 4️⃣ Authenticate:
gh auth login

13. Where Does gh Store Its Data?

You can edit the config file manually if you need to change defaults (e.g., default editor, git protocol, or hostname for GitHub Enterprise).

# Example ~/.config/gh/config.yml
git_protocol: ssh
editor: code --wait
prompt: disabled

14. Final Thoughts

GitHub CLI (gh) is deliberately built to be portable, secure, and easy to install across all major operating systems. By following the steps above, you can have a fully‑functional gh client on any machine—whether you’re on a personal laptop, a remote server, a CI runner, or inside a container.

If you ever run into an edge case not covered here, the official docs (https://cli.github.com/manual/) are an excellent companion, and the community on GitHub Discussions is quick to help.

Happy hacking! 🎉