Install Claude Code on Mac: a clean, complete setup

What you actually install

Claude Code is a single command line tool. You install it as a global npm package, you run the claude command from inside any project folder, and that is the whole product. There is no Mac app to download, no menu bar widget, no separate background service. The package name is @anthropic-ai/claude-code and it ships as JavaScript that runs on Node. Once it is installed, you talk to it the same way you would talk to a teammate over a terminal session. It reads your files, proposes edits, runs commands you approve, and keeps the conversation scoped to the folder you launched it in.

Before you install anything, decide where Claude Code will live on your machine. Most Mac developers already have Homebrew and a Node version manager. If you do not, that is fine, but you want to install Node through nvm rather than the system installer, because the global npm prefix that ships with the macOS Node package needs sudo and that path leads to confusing permission errors later. A clean nvm install gives you a writable global bin directory and lets you upgrade Node without breaking your shell.

Prerequisites for a clean install

You need three things in place before the install command will succeed. A current macOS with Xcode command line tools, Node 20 or newer, and an Anthropic account that can sign in to Claude Code. The Xcode tools are required because some npm dependencies compile small native pieces, and without them you get a node-gyp failure that looks scarier than it is. Run xcode-select --install once and let it finish. The first time you do this it can take ten minutes on a slow connection, so kick it off before you brew coffee rather than waiting on it once you have momentum.

If you do not have nvm, install it before anything else. Curl the install script, restart your terminal, then run nvm install 20 followed by nvm alias default 20. This handles three things at once. Your Node version is now under your control, your global npm prefix lives in your home directory, and your future self gets a clean upgrade path when Node 22 stabilizes. The whole process takes about five minutes and removes most of the surface area where Mac installs go wrong.

• macOS 13 Ventura or newer is the safe floor; older versions still work but get less attention from the team
• Node 20 LTS or Node 22 LTS, installed via nvm so you control the path and avoid sudo on global installs
• An Anthropic account with billing on file, since Claude Code authenticates against your account rather than a separate API key in most setups
• A terminal you actually like, whether that is the built in Terminal app, iTerm2, Ghostty, or Warp
• Git installed and configured with your name and email, because Claude Code reads your local git config to understand authorship

The install command

With Node in place, the install is one line. Open your terminal and run npm install -g @anthropic-ai/claude-code. The g flag puts the binary on your PATH so you can run claude from any folder. The download is small. Once it finishes, type claude --version and you should see a version string come back. If you see command not found, your global npm bin directory is not on your PATH, which usually means you installed Node with the system installer instead of nvm. Switch to nvm and reinstall.

Take a moment to look at where npm put the binary. Run which claude and note the path. It should point inside your nvm versions directory, somewhere like nvm slash versions slash node slash twenty something slash bin slash claude. If it points at usr slash local slash bin, you are running the system installer Node. That works for now but will produce permission errors the first time you upgrade. The cleanup is the same nvm reinstall described above, and doing it now while the project folder is empty is much cheaper than doing it later mid session.

First authentication

Run claude inside any project folder. The first run prompts you to authenticate. It opens a browser tab where you sign in to your Anthropic account, approves the local session, and writes a token to a config file in your home directory. After that the claude command starts a session bound to your account. You do not need to paste an API key into your shell, and you should not commit anything from your home directory config into git. If you ever need to log out, the claude logout subcommand clears the local token. Keep that subcommand in mind when you swap machines or hand a laptop to someone else for a demo.

Pointing Claude Code at a real project

Claude Code only sees the directory you launched it in. Change into a real project folder before you start the session. A small Next.js app, a Python script, or a static site all work. Once you are inside, run claude and ask it to read the README. That single round trip tells you whether the install is healthy, whether file permissions are correct, and whether the model can actually edit files in that folder without prompting you for sudo.

1. 1Open your terminal and cd into a real project folder, not your home directory
2. 2Run the claude command and wait for the session prompt
3. 3Ask it to summarize the project structure as a sanity check that file reading works
4. 4Ask it to add a comment to a single file so you can confirm the edit and approval flow
5. 5Run git diff to confirm the change landed the way you expected

Common install errors and what they really mean

Most install problems on Mac come from three sources. Permissions, architecture mismatches, and stale Node versions. EACCES on a global install means you tried to install into a system path without sudo, which is exactly the wrong fix. The right fix is to reinstall Node under nvm so your global bin lives in your home directory. ENOENT on the claude binary means the install succeeded but your PATH is missing the global bin directory. Echo PATH and confirm that the nvm versions directory is in there.

If the install finishes but claude --version hangs forever, you likely have a corporate proxy or a VPN that intercepts npm traffic. Disable the VPN for the install, or set HTTPS_PROXY in your shell config to point at the proxy and retry. None of these errors mean Claude Code is broken. They mean your Node environment needs a tune up. The same hygiene that keeps npm happy keeps Claude Code happy.

Keeping your install healthy

Updates ship through npm. Run npm install -g @anthropic-ai/claude-code again to pull the latest version. There is no auto updater. Members of the club at claudecodeclub.ai usually update once a week and post anything that changed in behavior, which saves you from chasing a regression you did not cause. Set a calendar reminder, or pair the update with your usual dependency bump day. The product moves fast and the cost of staying current is small.

When you update, run claude --version right after to confirm the new version actually replaced the old one. Sometimes a stale global symlink keeps pointing at the old binary, especially if you have multiple Node versions installed under nvm. If the version string did not change, switch to the Node version you actually want with nvm use and reinstall there. This takes thirty seconds and prevents an hour of confusion later when a behavior the release notes say is fixed still shows up in your session.

Working with proxies and corporate networks

If your machine sits behind a corporate proxy, set HTTP_PROXY and HTTPS_PROXY in your shell config before you run the install. The npm install will use them for the download, and Claude Code will use them for any outbound calls. If your proxy requires a custom certificate, point NODE_EXTRA_CA_CERTS at the certificate file so Node trusts the chain. None of this is exotic, but the symptoms when you skip it look mysterious. A hang on first run, a TLS error halfway through a session, or a generic network failure that does not match the actual problem.

Shell config that pays off later

Two small additions to your shell config make Claude Code easier to live with. The first is an alias for the project folders you open most. cdwork that jumps into your main work directory, cdside that jumps into your side projects folder. Claude Code only sees the directory you launched it in, so the alias is the difference between five keystrokes and twenty. The second is a function that runs claude with the current directory printed first, so you always know which project the new session is bound to. Neither of these is required and both of them save real time over a year of daily use.

Set your editor environment variable too. Many tasks Claude Code surfaces ask whether you want to open a file in your editor. If EDITOR is unset, it falls back to whatever the system thinks is your default, which is often not the editor you actually want. Set EDITOR to the command name of your real editor in your shell config and you stop fighting the prompt. For VS Code users that is code. For Cursor users that is cursor. For Neovim users that is nvim. Pick once, set once, forget about it.

Permissions and the approval prompt

By default, Claude Code asks before it runs any command that touches your system. The prompt shows the command, the working directory, and a one line reason. Read it, then approve or decline. Some commands run often enough that the prompt feels like friction. You can grant standing approval to a specific command in your project for the rest of the session, which keeps the safety net for surprises without nagging you on the dozenth git status. Standing approval expires when the session ends, so the next session starts fresh.

Resist the urge to grant blanket approval to everything on day one. The prompt is a learning tool as much as a safety check. Reading what Claude Code is about to run teaches you which commands it tends to reach for and why. By the end of the first week you will know which commands to wave through and which to slow down on. That intuition is worth more than the seconds the prompt costs you.

What claude code download actually means

There is no installer file to download from a website. Claude Code is distributed exclusively as an npm package, which means your package manager handles the download automatically when you run the install command. This is what Anthropic means when they describe claude code download - the package fetches from the npm registry and the binary lands in your global node bin directory. If you are looking for a dmg or pkg file, you will not find one. The npm path is intentional because it makes version management and updates dramatically simpler than a bundled app would.

The same npm distribution model means that claude code on the web is not a thing you install separately. Claude Code by Anthropic is the terminal tool. There is also a web interface at claude.ai where you can chat with Claude models in a browser, but that is a different product from the coding agent you install with npm. The claude code CLI is the tool this guide is about. It runs locally on your Mac, reads your files, and has full access to your working tree - capabilities that a browser tab cannot have.

Is there a claude code desktop app?

As of 2025, Claude Code does not ship as a standalone Mac desktop app with a dock icon. It runs inside your terminal. Some IDE integrations - VS Code and Cursor in particular - expose Claude Code functionality inside the editor UI, which can feel like a desktop app because you interact with it in a graphical window rather than a raw terminal prompt. But under the hood, those integrations still run the same npm package you installed globally. Uninstalling the npm package uninstalls the capability regardless of which editor surface you use.

The terminal-first design is a strength rather than a limitation. It means Claude Code runs wherever you run your development work, without requiring a separate app to be open. A single claude command invocation from inside a project folder is all the activation energy the tool needs. For developers who already live in the terminal, this is the right interface. For developers who prefer graphical tools, the Cursor and VS Code integrations give you a similar experience with a few more clicks.

How claude code login works

The first time you run the claude command after installing, it detects that no local session exists and kicks off the authentication flow. A browser tab opens pointing at your Anthropic account. You sign in or create a free account, approve access for the local session, and the browser redirects to a confirmation page. Back in your terminal, Claude Code receives the session token and writes it to a config file in your home directory under the .claude folder.

After that first claude code login, subsequent launches skip the browser step entirely. The token stays valid as long as your Anthropic session is active. If you log out of your Anthropic account in the browser, run claude logout in your terminal to clear the local token so the two stay in sync. On a shared machine or a machine you are about to hand off, always run claude logout before the handoff so the next person cannot continue your session.

Running Claude Code in IDEs and editors

Claude Code by Anthropic works outside the raw terminal too. The VS Code extension and the Cursor integration both surface the same agent inside the editor panel, so you can have a Claude Code session running alongside your open files without a separate terminal window. The setup is the same npm install you already did - the IDE extensions discover the globally installed binary. If the extension says it cannot find claude, check that the global npm bin directory is on the PATH that your IDE inherits when it launches.

IDE integration does not change what Claude Code can see. It still reads the folder your project is rooted in. Opening a file in the editor does not automatically expand Claude Code's context unless you tell it to read that file. The advantage of the IDE setup is that the diff view renders inline next to your code instead of in the terminal, which some developers find easier to review. Either interface runs the same model and the same tool set - the choice is purely about where you prefer to read diffs.

Verifying the full install

After install and login, run three quick checks to confirm everything is working. First, claude --version should return a version string. Second, which claude should return a path inside your nvm directory. Third, change into a real project folder, run claude, and ask it to list the top level files. If all three work without errors, your install is healthy. If any of them fail, the failure message usually tells you exactly what is wrong. Most first-install failures are PATH issues that a terminal restart and a which node check will expose.

1. 1Run claude --version and confirm a version string comes back
2. 2Run which claude and confirm the path is inside your nvm directory, not /usr/local/bin
3. 3Run node --version and confirm you are on Node 20 or newer
4. 4cd into a real project folder and run claude to open a session
5. 5Ask Claude Code to list the project structure as a final sanity check

Keeping Node and Claude Code in sync

Claude Code tracks Node releases closely because it uses newer JavaScript features. When you upgrade Node via nvm, reinstall the global package in the new version with the same npm install -g @anthropic-ai/claude-code command. The old binary stays on the old Node version unless you reinstall. Run nvm use 22 followed by the install command and both stay current together. Setting up nvm alias default 22 means new terminal tabs automatically use the right Node version, so you never forget which version a new shell inherits.

Where to go next

With Claude Code installed, the next two guides worth your time are the ones on first projects and on MCP servers. Walk through your first real session in our /guides/your-first-claude-code-project guide, then expand what Claude Code can see by following /guides/setting-up-mcp-servers. The install is the smallest part of using the tool well. The habits you build in the first week are what make the rest of it pay off, and the $9 a month club exists to compress that learning curve into a few sessions. The members who get the most out of the tool are the ones who invest in the setup once and then leave it alone, so do the careful work in week one and the rest of the year runs smoother for it.