← Back to daily report

setup.md

Changed on 2026-02-24 17:28:41 EST

Unified Diff

--- a/setup.md
+++ b/setup.md
@@ -2,29 +2,38 @@
 > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
 > Use this file to discover all available pages before exploring further.
 
-# Set up Claude Code
-
-> Install, authenticate, and start using Claude Code on your development machine.
+# Advanced setup
+
+> System requirements, platform-specific installation, version management, and uninstallation for Claude Code.
+
+This page covers system requirements, platform-specific installation details, updates, and uninstallation. For a guided walkthrough of your first session, see the [quickstart](/en/quickstart). If you've never used a terminal before, see the [terminal guide](/en/terminal-guide).
 
 ## System requirements
 
-* **Operating System**:
+Claude Code runs on the following platforms and configurations:
+
+* **Operating system**:
   * macOS 13.0+
-  * Windows 10 1809+ or Windows Server 2019+ ([see setup notes](#platform-specific-setup))
+  * Windows 10 1809+ or Windows Server 2019+
   * Ubuntu 20.04+
   * Debian 10+
-  * Alpine Linux 3.19+ ([additional dependencies required](#platform-specific-setup))
+  * Alpine Linux 3.19+
 * **Hardware**: 4 GB+ RAM
-* **Network**: Internet connection required (see [network configuration](/en/network-config#network-access-requirements))
-* **Shell**: Works best in Bash or Zsh
+* **Network**: internet connection required. See [network configuration](/en/network-config#network-access-requirements).
+* **Shell**: Bash, Zsh, PowerShell, or CMD. On Windows, [Git for Windows](https://git-scm.com/downloads/win) is required.
 * **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)
 
 ### Additional dependencies
 
-* **ripgrep**: Usually included with Claude Code. If search fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).
-* **[Node.js 18+](https://nodejs.org/en/download)**: Only required for [deprecated npm installation](#npm-installation-deprecated)
-
-## Installation
+* **ripgrep**: usually included with Claude Code. If search fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).
+
+## Install Claude Code
+
+<Tip>
+  Prefer a graphical interface? The [Desktop app](/en/desktop-quickstart) lets you use Claude Code without the terminal. Download it for [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) or [Windows](https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs).
+
+  New to the terminal? See the [terminal guide](/en/terminal-guide) for step-by-step instructions.
+</Tip>
 
 To install Claude Code, use one of the following methods:
 
@@ -47,6 +56,8 @@
     ```batch  theme={null}
     curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
     ```
+
+    **Windows requires [Git for Windows](https://git-scm.com/downloads/win).** Install it first if you don't have it.
 
     <Info>
       Native installations automatically update in the background to keep you on the latest version.
@@ -54,7 +65,7 @@
   </Tab>
 
   <Tab title="Homebrew">
-    ```sh  theme={null}
+    ```bash  theme={null}
     brew install --cask claude-code
     ```
 
@@ -74,176 +85,98 @@
   </Tab>
 </Tabs>
 
-After the installation process completes, navigate to your project and start Claude Code:
-
-```bash  theme={null}
-cd your-awesome-project
+After installation completes, open a terminal in the project you want to work in and start Claude Code:
+
+```bash  theme={null}
 claude
 ```
 
-If you encounter any issues during installation, consult the [troubleshooting guide](/en/troubleshooting).
-
-<Tip>
-  Run `claude doctor` after installation to check your installation type and version.
-</Tip>
-
-### Platform-specific setup
-
-**Windows**: Run Claude Code natively (requires [Git Bash](https://git-scm.com/downloads/win)) or inside WSL. Both WSL 1 and WSL 2 are supported, but WSL 1 has limited support and does not support features like Bash tool sandboxing.
-
-**Alpine Linux and other musl/uClibc-based distributions**:
+If you encounter any issues during installation, see the [troubleshooting guide](/en/troubleshooting).
+
+### Set up on Windows
+
+Claude Code on Windows requires [Git for Windows](https://git-scm.com/downloads/win) or WSL. You can launch `claude` from PowerShell, CMD, or Git Bash. Claude Code uses Git Bash internally to run commands. You do not need to run PowerShell as Administrator.
+
+**Option 1: Native Windows with Git Bash**
+
+Install [Git for Windows](https://git-scm.com/downloads/win), then run the install command from PowerShell or CMD.
+
+If Claude Code can't find your Git Bash installation, set the path in your [settings.json file](/en/settings):
+
+```json  theme={null}
+{
+  "env": {
+    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
+  }
+}
+```
+
+**Option 2: WSL**
+
+Both WSL 1 and WSL 2 are supported. WSL 2 supports [sandboxing](/en/sandboxing) for enhanced security. WSL 1 does not support sandboxing.
+
+### Alpine Linux and musl-based distributions
 
 The native installer on Alpine and other musl/uClibc-based distributions requires `libgcc`, `libstdc++`, and `ripgrep`. Install these using your distribution's package manager, then set `USE_BUILTIN_RIPGREP=0`.
 
-On Alpine:
+This example installs the required packages on Alpine:
 
 ```bash  theme={null}
 apk add libgcc libstdc++ ripgrep
 ```
 
-### Authentication
-
-#### For individuals
-
-1. **Claude Pro or Max plan** (recommended): Subscribe to Claude's [Pro or Max plan](https://claude.ai/pricing) for a unified subscription that includes both Claude Code and Claude on the web. Manage your account in one place and log in with your Claude.ai account.
-2. **Claude Console**: Connect through the [Claude Console](https://console.anthropic.com) and complete the OAuth process. Requires active billing in the Anthropic Console. A "Claude Code" workspace is automatically created for usage tracking and cost management. You can't create API keys for the Claude Code workspace; it's dedicated exclusively for Claude Code usage.
-
-#### For teams and organizations
-
-1. **Claude for Teams or Enterprise** (recommended): Subscribe to [Claude for Teams](https://claude.com/pricing#team-&-enterprise) or [Claude for Enterprise](https://anthropic.com/contact-sales) for centralized billing, team management, and access to both Claude Code and Claude on the web. Team members log in with their Claude.ai accounts.
-2. **Claude Console with team billing**: Set up a shared [Claude Console](https://console.anthropic.com) organization with team billing. Invite team members and assign roles for usage tracking.
-3. **Cloud providers**: Configure Claude Code to use [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) for deployments with your existing cloud infrastructure.
-
-### Install a specific version
-
-The native installer accepts either a specific version number or a release channel (`latest` or `stable`). The channel you choose at install time becomes your default for auto-updates. See [Configure release channel](#configure-release-channel) for more information.
-
-To install the latest version (default):
-
-<Tabs>
-  <Tab title="macOS, Linux, WSL">
-    ```bash  theme={null}
-    curl -fsSL https://claude.ai/install.sh | bash
-    ```
-  </Tab>
-
-  <Tab title="Windows PowerShell">
-    ```powershell  theme={null}
-    irm https://claude.ai/install.ps1 | iex
-    ```
-  </Tab>
-
-  <Tab title="Windows CMD">
-    ```batch  theme={null}
-    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
-    ```
-  </Tab>
-</Tabs>
-
-To install the stable version:
-
-<Tabs>
-  <Tab title="macOS, Linux, WSL">
-    ```bash  theme={null}
-    curl -fsSL https://claude.ai/install.sh | bash -s stable
-    ```
-  </Tab>
-
-  <Tab title="Windows PowerShell">
-    ```powershell  theme={null}
-    & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable
-    ```
-  </Tab>
-
-  <Tab title="Windows CMD">
-    ```batch  theme={null}
-    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd
-    ```
-  </Tab>
-</Tabs>
-
-To install a specific version number:
-
-<Tabs>
-  <Tab title="macOS, Linux, WSL">
-    ```bash  theme={null}
-    curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
-    ```
-  </Tab>
-
-  <Tab title="Windows PowerShell">
-    ```powershell  theme={null}
-    & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
-    ```
-  </Tab>
-
-  <Tab title="Windows CMD">
-    ```batch  theme={null}
-    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd
-    ```
-  </Tab>
-</Tabs>
-
-### Binary integrity and code signing
-
-* SHA256 checksums for all platforms are published in the release manifests, currently located at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json` (example: replace `{VERSION}` with `2.0.30`)
-* Signed binaries are distributed for the following platforms:
-  * macOS: Signed by "Anthropic PBC" and notarized by Apple
-  * Windows: Signed by "Anthropic, PBC"
-
-## NPM installation (deprecated)
-
-NPM installation is deprecated. Use the [native installation](#installation) method when possible. To migrate an existing npm installation to native, run `claude install`.
-
-**Global npm installation**
-
-```sh  theme={null}
-npm install -g @anthropic-ai/claude-code
-```
-
-<Warning>
-  Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks.
-  If you encounter permission errors, see [troubleshooting permission errors](/en/troubleshooting#command-not-found-claude-or-permission-errors) for recommended solutions.
-</Warning>
-
-## Windows setup
-
-**Option 1: Claude Code within WSL**
-
-* Both WSL 1 and WSL 2 are supported
-* WSL 2 supports [sandboxing](/en/sandboxing) for enhanced security. WSL 1 does not support sandboxing.
-
-**Option 2: Claude Code on native Windows with Git Bash**
-
-* Requires [Git for Windows](https://git-scm.com/downloads/win)
-* For portable Git installations, specify the path to your `bash.exe`:
-  ```powershell  theme={null}
-  $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
-  ```
+Then set `USE_BUILTIN_RIPGREP` to `0` in your [settings.json file](/en/settings#environment-variables):
+
+```json  theme={null}
+{
+  "env": {
+    "USE_BUILTIN_RIPGREP": "0"
+  }
+}
+```
+
+## Verify your installation
+
+After installing, confirm Claude Code is working:
+
+```bash  theme={null}
+claude --version
+```
+
+For a more detailed check of your installation and configuration, run [`claude doctor`](/en/troubleshooting#get-more-help):
+
+```bash  theme={null}
+claude doctor
+```
+
+## Authenticate
+
+Claude Code requires a Pro, Max, Teams, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access. You can also use Claude Code with a third-party API provider like [Amazon Bedrock](/en/amazon-bedrock), [Google Vertex AI](/en/google-vertex-ai), or [Microsoft Foundry](/en/microsoft-foundry).
+
+After installing, log in by running `claude` and following the browser prompts. See [Authentication](/en/authentication) for all account types and team setup options.
 
 ## Update Claude Code
 
-### Auto updates
-
-Claude Code automatically keeps itself up to date to ensure you have the latest features and security fixes.
-
-* **Update checks**: Performed on startup and periodically while running
-* **Update process**: Downloads and installs automatically in the background
-* **Notifications**: You'll see a notification when updates are installed
-* **Applying updates**: Updates take effect the next time you start Claude Code
+Native installations automatically update in the background. You can [configure the release channel](#configure-release-channel) to control whether you receive updates immediately or on a delayed stable schedule, or [disable auto-updates](#disable-auto-updates) entirely. Homebrew and WinGet installations require manual updates.
+
+### Auto-updates
+
+Claude Code checks for updates on startup and periodically while running. Updates download and install in the background, then take effect the next time you start Claude Code.
 
 <Note>
   Homebrew and WinGet installations do not auto-update. Use `brew upgrade claude-code` or `winget upgrade Anthropic.ClaudeCode` to update manually.
 
   **Known issue:** Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later.
+
+  Homebrew keeps old versions on disk after upgrades. Run `brew cleanup claude-code` periodically to reclaim disk space.
 </Note>
 
 ### Configure release channel
 
-Configure which release channel Claude Code follows for both auto-updates and `claude update` with the `autoUpdatesChannel` setting:
-
-* `"latest"` (default): Receive new features as soon as they're released
-* `"stable"`: Use a version that is typically about one week old, skipping releases with major regressions
+Control which release channel Claude Code follows for auto-updates and `claude update` with the `autoUpdatesChannel` setting:
+
+* `"latest"`, the default: receive new features as soon as they're released
+* `"stable"`: use a version that is typically about one week old, skipping releases with major regressions
 
 Configure this via `/config` → **Auto-update channel**, or add it to your [settings.json file](/en/settings):
 
@@ -253,70 +186,190 @@
 }
 ```
 
-For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](/en/settings#settings-files).
+For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](/en/permissions#managed-settings).
 
 ### Disable auto-updates
 
-Set the `DISABLE_AUTOUPDATER` environment variable in your shell or [settings.json file](/en/settings):
-
-```bash  theme={null}
-export DISABLE_AUTOUPDATER=1
+Set `DISABLE_AUTOUPDATER` to `"1"` in the `env` key of your [settings.json file](/en/settings#environment-variables):
+
+```json  theme={null}
+{
+  "env": {
+    "DISABLE_AUTOUPDATER": "1"
+  }
+}
 ```
 
 ### Update manually
 
+To apply an update immediately without waiting for the next background check, run:
+
 ```bash  theme={null}
 claude update
 ```
 
+## Advanced installation options
+
+These options are for version pinning, migrating from npm, and verifying binary integrity.
+
+### Install a specific version
+
+The native installer accepts either a specific version number or a release channel (`latest` or `stable`). The channel you choose at install time becomes your default for auto-updates. See [configure release channel](#configure-release-channel) for more information.
+
+To install the latest version (default):
+
+<Tabs>
+  <Tab title="macOS, Linux, WSL">
+    ```bash  theme={null}
+    curl -fsSL https://claude.ai/install.sh | bash
+    ```
+  </Tab>
+
+  <Tab title="Windows PowerShell">
+    ```powershell  theme={null}
+    irm https://claude.ai/install.ps1 | iex
+    ```
+  </Tab>
+
+  <Tab title="Windows CMD">
+    ```batch  theme={null}
+    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
+    ```
+  </Tab>
+</Tabs>
+
+To install the stable version:
+
+<Tabs>
+  <Tab title="macOS, Linux, WSL">
+    ```bash  theme={null}
+    curl -fsSL https://claude.ai/install.sh | bash -s stable
+    ```
+  </Tab>
+
+  <Tab title="Windows PowerShell">
+    ```powershell  theme={null}
+    & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable
+    ```
+  </Tab>
+
+  <Tab title="Windows CMD">
+    ```batch  theme={null}
+    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd
+    ```
+  </Tab>
+</Tabs>
+
+To install a specific version number:
+
+<Tabs>
+  <Tab title="macOS, Linux, WSL">
+    ```bash  theme={null}
+    curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
+    ```
+  </Tab>
+
+  <Tab title="Windows PowerShell">
+    ```powershell  theme={null}
+    & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
+    ```
+  </Tab>
+
+  <Tab title="Windows CMD">
+    ```batch  theme={null}
+    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd
+    ```
+  </Tab>
+</Tabs>
+
+### Deprecated npm installation
+
+npm installation is deprecated. The native installer is faster, requires no dependencies, and auto-updates in the background. Use the [native installation](#install-claude-code) method when possible.
+
+#### Migrate from npm to native
+
+If you previously installed Claude Code with npm, switch to the native installer:
+
+```bash  theme={null}
+# Install the native binary
+curl -fsSL https://claude.ai/install.sh | bash
+
+# Remove the old npm installation
+npm uninstall -g @anthropic-ai/claude-code
+```
+
+You can also run `claude install` from an existing npm installation to install the native binary alongside it, then remove the npm version.
+
+#### Install with npm
+
+If you need npm installation for compatibility reasons, you must have [Node.js 18+](https://nodejs.org/en/download) installed. Install the package globally:
+
+```bash  theme={null}
+npm install -g @anthropic-ai/claude-code
+```
+
+<Warning>
+  Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks. If you encounter permission errors, see [troubleshooting permission errors](/en/troubleshooting#permission-errors-during-installation).
+</Warning>
+
+### Binary integrity and code signing
+
+You can verify the integrity of Claude Code binaries using SHA256 checksums and code signatures.
+
+* SHA256 checksums for all platforms are published in the release manifests at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json`. Replace `{VERSION}` with a version number such as `2.0.30`.
+* Signed binaries are distributed for the following platforms:
+  * **macOS**: signed by "Anthropic PBC" and notarized by Apple
+  * **Windows**: signed by "Anthropic, PBC"
+
 ## Uninstall Claude Code
 
-If you need to uninstall Claude Code, follow the instructions for your installation method.
+To remove Claude Code, follow the instructions for your installation method.
 
 ### Native installation
 
 Remove the Claude Code binary and version files:
 
-**macOS, Linux, WSL:**
-
-```bash  theme={null}
-rm -f ~/.local/bin/claude
-rm -rf ~/.local/share/claude
-```
-
-**Windows PowerShell:**
-
-```powershell  theme={null}
-Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
-Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force
-```
-
-**Windows CMD:**
-
-```batch  theme={null}
-del "%USERPROFILE%\.local\bin\claude.exe"
-rmdir /s /q "%USERPROFILE%\.local\share\claude"
-```
+<Tabs>
+  <Tab title="macOS, Linux, WSL">
+    ```bash  theme={null}
+    rm -f ~/.local/bin/claude
+    rm -rf ~/.local/share/claude
+    ```
+  </Tab>
+
+  <Tab title="Windows PowerShell">
+    ```powershell  theme={null}
+    Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
+    Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force
+    ```
+  </Tab>
+</Tabs>
 
 ### Homebrew installation
 
+Remove the Homebrew cask:
+
 ```bash  theme={null}
 brew uninstall --cask claude-code
 ```
 
 ### WinGet installation
+
+Remove the WinGet package:
 
 ```powershell  theme={null}
 winget uninstall Anthropic.ClaudeCode
 ```
 
-### NPM installation
+### npm
+
+Remove the global npm package:
 
 ```bash  theme={null}
 npm uninstall -g @anthropic-ai/claude-code
 ```
 
-### Clean up configuration files (optional)
+### Remove configuration files
 
 <Warning>
   Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.
@@ -324,38 +377,28 @@
 
 To remove Claude Code settings and cached data:
 
-**macOS, Linux, WSL:**
-
-```bash  theme={null}
-# Remove user settings and state
-rm -rf ~/.claude
-rm ~/.claude.json
-
-# Remove project-specific settings (run from your project directory)
-rm -rf .claude
-rm -f .mcp.json
-```
-
-**Windows PowerShell:**
-
-```powershell  theme={null}
-# Remove user settings and state
-Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
-Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
-
-# Remove project-specific settings (run from your project directory)
-Remove-Item -Path ".claude" -Recurse -Force
-Remove-Item -Path ".mcp.json" -Force
-```
-
-**Windows CMD:**
-
-```batch  theme={null}
-REM Remove user settings and state
-rmdir /s /q "%USERPROFILE%\.claude"
-del "%USERPROFILE%\.claude.json"
-
-REM Remove project-specific settings (run from your project directory)
-rmdir /s /q ".claude"
-del ".mcp.json"
-```
+<Tabs>
+  <Tab title="macOS, Linux, WSL">
+    ```bash  theme={null}
+    # Remove user settings and state
+    rm -rf ~/.claude
+    rm ~/.claude.json
+
+    # Remove project-specific settings (run from your project directory)
+    rm -rf .claude
+    rm -f .mcp.json
+    ```
+  </Tab>
+
+  <Tab title="Windows PowerShell">
+    ```powershell  theme={null}
+    # Remove user settings and state
+    Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
+    Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
+
+    # Remove project-specific settings (run from your project directory)
+    Remove-Item -Path ".claude" -Recurse -Force
+    Remove-Item -Path ".mcp.json" -Force
+    ```
+  </Tab>
+</Tabs>