If you've tried running brew install copilot-cli and received an error, you're not alone. This is one of the most common installation issues because GitHub Copilot CLI is not available through Homebrew. This guide covers the correct installation methods and troubleshooting common errors.
Why "brew install copilot-cli" Doesn't Work
GitHub Copilot CLI is distributed through npm (Node Package Manager), not Homebrew. When you run brew install copilot-cli, you'll see:
$ brew install copilot-cli
Error: No available formula with the name "copilot-cli".
Or if searching:
$ brew search copilot
No formula or cask found for "copilot".
This is expected behavior—not an error with your Homebrew installation.
Correct Installation Methods
Method 1: npm (Recommended)
The official way to install GitHub Copilot CLI:
# Install the official package
npm install -g @github/copilot-cli
# Verify installation
copilot --version
Prerequisites:
- Node.js 18 or later
- npm 8 or later
- GitHub Copilot subscription (Individual, Business, or Enterprise)
Method 2: npx (No Global Install)
Run Copilot CLI without installing globally:
# Run directly without installation
npx @github/copilot-cli "explain this code"
# Or for specific commands
npx @github/copilot-cli suggest "git command to undo last commit"
Method 3: Windows winget
On Windows, you can use the Windows Package Manager:
# Install via winget
winget install GitHub.CopilotCLI
# Verify installation
copilot --version
Method 4: From Source
For contributors or advanced users:
# Clone the repository
git clone https://github.com/github/copilot-cli.git
cd copilot-cli
# Install dependencies
npm install
# Link globally
npm link
Common Installation Errors and Fixes
Error: "npm: command not found"
You need to install Node.js, which includes npm:
macOS (using Homebrew):
brew install node
Linux (Ubuntu/Debian):
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
Windows: Download from nodejs.org or use winget:
winget install OpenJS.NodeJS.LTS
Error: "permission denied" During npm Install
Don't use sudo with npm global installs. Instead, fix npm permissions:
Option 1: Change npm's default directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
Option 2: Use nvm (Node Version Manager)
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Install Node.js via nvm (handles permissions automatically)
nvm install 20
nvm use 20
# Now install copilot-cli
npm install -g @github/copilot-cli
Error: "command not found: copilot" After Installation
Your PATH doesn't include npm's global bin directory:
Find npm's bin directory:
npm bin -g
# Example output: /usr/local/bin or ~/.npm-global/bin
Add to your shell profile:
For zsh (macOS default):
echo 'export PATH=$PATH:$(npm bin -g)' >> ~/.zshrc
source ~/.zshrc
For bash:
echo 'export PATH=$PATH:$(npm bin -g)' >> ~/.bashrc
source ~/.bashrc
Error: "EACCES: permission denied, mkdir"
This usually means npm is trying to write to a protected directory:
# Check where npm is trying to install
npm config get prefix
# If it shows /usr/local, fix with:
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
Error: "npm ERR! 404 Not Found - GET https://registry.npmjs.org/@github%2fcopilot-cli"
The package name might be incorrect or you may not have access:
# Make sure you're using the correct package name
npm install -g @github/copilot-cli
# NOT these (deprecated/incorrect):
# npm install -g copilot-cli # Wrong
# npm install -g github-copilot-cli # Wrong
Error: "You need a GitHub Copilot subscription"
After installation, you need to authenticate:
# Login to GitHub
copilot auth login
# Or use GitHub CLI if available
gh auth login
copilot auth login
Migrating from @githubnext to @github Package
If you installed the older technical preview package:
# Remove old package
npm uninstall -g @githubnext/github-copilot-cli
# Install official package
npm install -g @github/copilot-cli
# Verify
copilot --version
Your configuration and authentication will be preserved.
Verifying Your Installation
After successful installation, verify everything works:
# Check version
copilot --version
# Check authentication status
copilot auth status
# Test with a simple query
copilot suggest "how to list all files in current directory"
Expected output:
copilot version 1.x.x
Authenticated as: your-github-username
Alternative: GitHub CLI Extension
If you prefer using GitHub CLI (gh), Copilot is also available as an extension:
# Install GitHub CLI first (this one IS available via Homebrew)
brew install gh
# Login to GitHub
gh auth login
# Install Copilot extension
gh extension install github/gh-copilot
# Use via gh
gh copilot suggest "git command to squash last 3 commits"
This method works well if you're already using gh for other GitHub operations.
Node.js Version Requirements
GitHub Copilot CLI requires Node.js 18 or later. Check your version:
node --version
# Should be v18.x.x or higher
If your version is older, upgrade using your package manager or nvm:
# Using nvm (recommended)
nvm install 20
nvm use 20
# Using Homebrew
brew upgrade node
# Verify
node --version
Troubleshooting Checklist
If installation still fails, work through this checklist:
- Node.js 18+ installed (
node --version) - npm 8+ installed (
npm --version) - Using correct package name (
@github/copilot-cli) - npm global bin in PATH (
echo $PATH | grep npm) - No permission issues (
npm config get prefixshows user-writable path) - GitHub Copilot subscription active
- Authenticated (
copilot auth status)