Home

Install Claude Code on Mac

Claude Code is an AI assistant that lives in your Terminal and helps you write, debug, and understand code. Think of it as having a knowledgeable coding partner available whenever you need help. Whether you’re a complete beginner or an experienced developer, Claude Code can accelerate your workflow and help you learn.

This guide walks you through installation step by step, with detailed instructions for beginners.

Overview

• Open Terminal
• Install Claude Code
• Configure your API connection
• Start using Claude Code

Key Concepts

• Terminal: A built-in Mac app where you type commands instead of clicking buttons. It’s how you’ll interact with Claude Code.
• Claude Code: An AI coding assistant you run in Terminal. It can answer questions, write code, and help you understand existing projects.

What You’ll Need

• A Mac computer (macOS 13.0 Ventura or newer)
• Internet connection
• Claude Pro/Max subscription or API key
• 5 - 10 minutes

Step 1: Open Terminal

• Press Command (⌘) + Space to open Spotlight search
• Type Terminal
• Press Return (or click Terminal, a black square icon, in the results)
• A Terminal window will open with a blinking cursor

Tip: Keep Terminal open for the next steps.

Step 2: Install Claude Code

In Terminal, copy and paste this command, then press Return:

curl -fsSL https://claude.ai/install.sh | bash

• Wait for Claude Code to install (1-2 minutes)
• The window may show no messages while it downloads — this is normal, just wait
• When installation is complete, close and reopen Terminal, then verify by typing:

   claude --version
  

• You should see the version number of Claude Code
• If you see zsh: command not found: claude instead, run these two lines (they tell your Mac where to find Claude Code), then try claude --version again:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
  

Alternative: Install with Homebrew

If you use Homebrew, you can install Claude Code with:

brew install --cask claude-code

Tip: Run claude doctor after installation to check that everything is set up correctly.

Step 3: Connect to Your Anthropic Account

Option A. Use your Claude Pro or Max subscription

• In Terminal, type:

   claude
  

• Claude tries to open a browser. If it doesn’t open automatically, press c to copy the login link, then paste it into your browser.
• Log in to your Claude.ai account (this may happen automatically)
• Click Authorize. The browser should say you’re logged in, and Terminal shows a success message.
• Only if the browser shows a long code instead, click Copy Code, go back to Terminal, paste it at Paste code here if prompted (press Command (⌘) + V), and press Return.
• Follow the instructions to complete the setup

Option B. Use Anthropic API key

If you have an Anthropic API key instead of a Claude subscription:

• First, get your API key from the Anthropic Console
• In Terminal, type:

   export ANTHROPIC_API_KEY="your-api-key-here"
  

  Replace your-api-key-here with your actual API key

• To make this permanent (so you don’t have to set it every time), add it to your shell profile:

   echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
  

  Replace your-api-key-here with your actual API key

• Close and reopen Terminal for the changes to take effect
• Start Claude Code by typing claude. The first time, it asks whether you want to use the API key it found. Choose Yes. (If you pick No by mistake, type /config and turn on Use custom API key.)

Note: If you’re using an older Mac with bash instead of zsh, replace ~/.zshrc with ~/.bash_profile in the command above.

Option C. Use OpenRouter API (pay as you go)

OpenRouter is a unified API gateway that provides access to 500+ large language models through a single API key. This can be an economical way to use Claude Code, as you pay only for usage and can choose from models at various price points.

• Sign up at openrouter.ai and log in
• Click Get API key and copy the key to a safe location
• Set the required environment variables before starting Claude Code:

   export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
   export ANTHROPIC_AUTH_TOKEN="your-openrouter-api-key"
   export ANTHROPIC_API_KEY=""
   export ANTHROPIC_DEFAULT_SONNET_MODEL="~anthropic/claude-sonnet-latest"
   export ANTHROPIC_DEFAULT_OPUS_MODEL="~anthropic/claude-opus-latest"
   export ANTHROPIC_DEFAULT_HAIKU_MODEL="~anthropic/claude-haiku-latest"
  

• Start Claude Code:

   claude
  

• Verify the connection by typing /status in Claude Code

Notes:

• Replace your-openrouter-api-key with your actual OpenRouter API key
• ANTHROPIC_API_KEY must be explicitly set to empty
• To use alternative models, they must support tool use capabilities. You can override models with:

   export ANTHROPIC_DEFAULT_SONNET_MODEL="model-provider/model-name"
  

• Browse available models at openrouter.ai/models
• Free (:free) models are limited to 50 requests per day, which a single Claude Code task can use up quickly
• The models shown above are paid models — check their prices at openrouter.ai/models before using them
• Claude Code is only guaranteed to work with Anthropic models through OpenRouter
• See the official OpenRouter guide for more details

Option D. Use Anthropic API via Microsoft Foundry (Azure)

This option is for organizations using Azure-hosted Claude models. In the Terminal window, paste this code to define environment variables (before starting Claude):

# Enable Microsoft Foundry integration
export CLAUDE_CODE_USE_FOUNDRY=1
# Azure resource name
export ANTHROPIC_FOUNDRY_RESOURCE=xxxx-eastus2
# Set models to your resource's deployment names
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5
export ANTHROPIC_FOUNDRY_API_KEY=your_api_key

Note: Replace xxxx-eastus2 with your Foundry Resource name (do not use the entire base URL). Replace your_api_key with your complete API key from your Azure portal.

Then start Claude Code by typing claude.

Step 4: Test Claude Code

You’re all set! Here’s how to use Claude Code:

• In Terminal, type:

   claude
  

• It asks you a few questions before getting ready to chat
• To see if it works, ask a general question such as “Explain quantum computing.”

Step 5: Navigate to Your Project

• If you have a project in your Mac folders, you can navigate to it:

   cd ~/Documents/test_claude
  

  Replace test_claude with your actual project folder name

• Then start Claude:

   claude
  

• Start by asking Claude to explain the codebase to you.
• You can ask Claude to make changes.
• Test your code in your preferred IDE.

Note: Claude operates inside a project folder. It defines writing permissions in the folder and saves settings in that folder. It’s Claude’s workspace.

Step 6: Update Claude Code

Claude Code installed via the native installer automatically updates itself in the background. You can also manually trigger an update:

• In Terminal, type:

   claude update
  

• Claude Code will check for updates and install the latest version

Note: Don’t use sudo to run or update Claude Code — it can leave root-owned files in your ~/.claude folder that cause permission errors the next time you run Claude Code normally.

Note: Homebrew installations do not auto-update. Run brew upgrade claude-code periodically to get the latest version.

Next Steps

• VS Code Getting Started - Learn to use VS Code, a popular code editor
• Claude Code in VS Code (Mac) - Run Claude Code inside VS Code
• Writing a Research Paper with Claude Code - Use Claude Code for academic writing

How to Open Terminal Again

After closing Terminal, here’s how to open it again:

• Press Command (⌘) + Space to open Spotlight search
• Type Terminal
• Press Return
• A Terminal window will open

Troubleshooting

First step: Run Claude Doctor

If something isn’t working, run this command first:

claude doctor

It checks your installation and reports any issues.

Installation script fails

• Make sure you have macOS 13.0 or newer
• Try the Homebrew alternative: brew install --cask claude-code
• Check your internet connection and try again

Claude Code commands not found

• Close Terminal completely (click Terminal in the menu bar, then Quit Terminal)
• Open Terminal again
• Try claude --version to check if it’s installed
• If it still says command not found, run these two lines, then try claude --version again:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
  

Authentication fails

• Make sure you have an active Claude Pro/Max subscription or valid API key
• Try running claude again and complete the login process
• Check that your browser opened the correct authorization page

Tips for Mac Users

Finding Project Paths

To find the path to a folder:

• Open Finder
• Navigate to your project folder
• Drag and drop the folder into Terminal - the full path will appear!

Using Different Terminal Apps

You can also use other terminal apps like:

• iTerm2 (popular alternative with more features)
• Warp (modern terminal with AI features)
• Hyper (cross-platform terminal)

Claude Code works with all of them!

Need Help?

• For Claude Code issues: Claude Code GitHub
• For official setup docs: Claude Code Setup Guide

Last updated: February 2026