Most Claude Code install guides skip the part where things actually go wrong. They show you the command, wish you luck, and leave you Googling “why does Claude’s command not work” at 11 pm. I’ve been there, and it’s avoidable.
The install itself is quick. One command on Mac or Linux, a few extra steps on Windows, and you’re in. What really messes things up is skipping the basics. If you use the wrong OS version, forget to install Git for Windows, or try doing it with a free Claude account that doesn’t even give access you’re going to get stuck. And the worst part? None of these issues is obvious until something actually breaks.
Honestly, the best way to avoid all this is to treat the setup like a recipe. Go through it once properly before you even start, instead of jumping in and trying to figure things out only when errors pop up. It saves a lot of time and frustration. Claude Code is a terminal-based tool, so your shell environment matters more than most people expect. Get that right, and the rest takes five minutes.
[IMAGE: Claude Code install command running in a macOS terminal window]
What to check before you run a single command
I never start an install blind. Checking the Claude code requirements first takes two minutes and saves ten. Here’s what the tool actually needs to run.
Your operating system has to be one of the supported versions. Claude Code works on macOS 13 or later, Ubuntu 20.04 or later, Debian 10 or later, Alpine Linux 3.19 or later, and Windows 10 version 1809 or later (also Windows Server 2019+). Anything older than that and you’re fighting the tool before you’ve even launched it.
You also need a working shell. Bash, Zsh, PowerShell, and CMD all work. On Windows, Git for Windows is required unless you go with WSL. You’ll need an internet connection and at least 4 GB of RAM. That last one rarely causes issues, but it’s worth knowing.
The account requirement is what surprises people. Claude Code is not included with the free Claude AI plan. You need a Pro, Max, Teams, Enterprise, or Console account. If your install runs fine but login fails, check this first before assuming something is broken.
| Requirement | What’s needed | Common mistake |
|---|---|---|
| Operating system | macOS 13+, Ubuntu 20.04+, Debian 10+, Alpine 3.19+, Windows 10 1809+ | Running on an older or unsupported distro |
| Shell | Bash, Zsh, PowerShell, or CMD | No shell configured on a fresh Windows setup |
| Windows dependency | Git for Windows or WSL | Skipping Git install and wondering why it fails |
| RAM | 4 GB minimum | Rarely an issue, but worth confirming |
| Account | Pro, Max, Teams, Enterprise, or Console | Assuming the free plan includes Claude Code |
[IMAGE: Claude Code install requirements checklist displayed across Mac, Windows, and Linux screens]
The three ways to do Claude Code install
There are three real install paths: native installer, Homebrew, and WinGet. The native installer is my pick almost every time. It’s the fastest, has no extra dependencies, and this matters because it auto-updates in the background. You install it once, and it quietly keeps itself up to date.
Homebrew and WinGet both work fine, but they don’t auto-update. If you forget to run brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode periodically, you end up on a stale version and might miss bug fixes. Not catastrophic, but annoying.
For most people on macOS or Linux, the native install is a single command. On Windows, PowerShell and CMD each have their own install script.
After installation finishes, open a terminal in your project folder and run:
- Claude to start the tool
- Claude –version to confirm the install worked
- Claude, doctor, if anything looks off
That last command is underrated. It checks your setup and flags issues specifically, which beats staring at a generic error message.
Claude Code install on Windows: do this first
Windows is where I see the most installation confusion, and it almost always comes down to one thing: Git for Windows not being installed before Claude Code. If you’re setting things up for the first time, it’s worth following the complete Windows installation guide before proceeding. Install Git for Windows first. Then run your chosen installer from PowerShell or CMD. You don’t need administrator privileges for this, which is a relief.
If Claude Code can’t locate Git Bash after installation, the fix is straightforward. You point it to the bash.exe path inside your Claude code settings file. That one environment variable clears the issue almost every time.
WSL is the other Windows option. WSL 1 and WSL 2 both work, but WSL 2 supports sandboxing, which adds a layer of security I prefer when working on anything sensitive.
Claude Code install on macOS and Linux
The native install script handles everything on macOS and Linux. Run it, let it finish, open your project, and you’re ready. If you’re on Linux, refer to the complete Linux setup guide. If you prefer Homebrew, the install command is just as clean, but remember the manual upgrade responsibility that comes with it.
On Alpine Linux or other musl-based distributions, there’s one extra step. You need to install libgcc, libstdc++, and ripgrep through your package manager before running Claude Code. You also set USE_BUILTIN_RIPGREP to 0 in your configuration file. It sounds fiddly, but it’s a ten-second fix once you know it exists.
The claude code settings worth knowing about early
I don’t usually recommend touching configuration files on day one. Most people don’t need to. But there are a handful of Claude code settings worth knowing before a small issue turns into a confusing afternoon.
The auto-update channel is one. By default, Claude Code follows the latest channel, meaning you get new features as soon as they ship. If you want something more conservative, say you’re using this in a team environment and want a bit more stability, you can switch to stable, which runs about a week behind and skips releases with known regressions.
On Windows, the most practically useful setting is the Git Bash path variable. If Claude Code can’t find Git Bash automatically, setting CLAUDE_CODE_GIT_BASH_PATH in your configuration file points it to the right place. Takes thirty seconds.
If you’re managing a setup where auto-updates would cause problems, you can disable the auto-updater entirely through the environment settings. That’s mostly relevant for enterprise or controlled environments, not personal machines.