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.

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.