Why You Should Not Install Claude Code Globally: Official Best Practices and Proxy Setup

Why You Should Not Install Claude Code Globally

When people first start using the Claude Code CLI, their instinct is often to install it globally with npm install -g @anthropic-ai/claude-code. That way they can run claude from any directory, which feels convenient.

The problem is that the official recommendation is actually the opposite: do not rely on a global install. Install it locally inside each project instead. This article explains why, then shows how to migrate and keep the same convenience through an alias and proxy configuration.

1. Why a global install is not ideal

A global install is convenient, but it creates several real problems:

1. Version conflicts

   • A global install gives you only one version.
   • If project A needs a newer version and project B still depends on an older one, they fight each other.

2. Poor portability

   • A global install is not recorded in package.json.
   • If you hand the project to someone else, npm install will not give them the same claude CLI automatically.

3. Harder debugging and upgrades

   • The project dependencies and the CLI tool version drift apart.
   • When something breaks, it becomes harder to tell whether the problem is in your code or in the CLI version.

4. Hidden configuration problems

   • The official /doctor check often reports messages like:

   Config mismatch: running npm-global but config says unknown
   

   That is one of the classic symptoms of a global install.

So the better pattern is simple: install Claude Code locally per project.

2. How to check for and remove a global install

First, confirm whether you installed it globally:

which claude
type -a claude

If the path looks something like this:

/Users/xxx/.nvm/versions/node/v20.19.2/bin/claude

then you are running the global version.

To remove it:

npm uninstall -g @anthropic-ai/claude-code

3. Install Claude Code locally

Move into your project directory, for example:

cd /Users/stevenlv/mylab/20250904claude

Install Claude Code into devDependencies:

npm install -D @anthropic-ai/claude-code

Now the version is recorded in package.json, and anyone else can reproduce the same environment with a normal npm install.

To run it:

npx claude status

Or add a script in package.json:

{
  "scripts": {
    "claude": "claude"
  }
}

Then run:

npm run claude status

4. Use an alias so you can still type claude

Add this to ~/.zshrc or ~/.bashrc:

alias claude="npx --no-install claude"

Then reload your shell:

source ~/.zshrc

Now the behavior becomes much better:

• inside a project that has Claude Code installed locally, typing claude runs the project version
• in a directory without a local install, it fails immediately instead of silently pulling in a global or ad hoc version

5. Why --no-install matters

If you write this:

alias claude="npx claude"

then when Claude Code is not installed locally, npx may download the latest version from npm automatically and run it.

That creates several problems:

• the CLI version can drift away from what the project expects
• historical issues become hard to reproduce
• you may get silent upgrades that introduce compatibility bugs

By adding --no-install, you force the alias to:

• use only the locally installed version
• fail immediately if the dependency is missing
• keep the project environment predictable

That gives you convenience without giving up control.

6. Proxy setup, optional but highly recommended

If you are in mainland China or use a proxy for general network access, the CLI may also need proxy settings. A practical approach is to define them in ~/.zshrc:

# HTTP/HTTPS proxy
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890

# Local addresses that should bypass the proxy
export NO_PROXY=localhost,127.0.0.1,::1

Then reload your shell:

source ~/.zshrc

Verify that the proxy works:

npx claude status
npx claude doctor

If the proxy is configured correctly, the API requests should work normally.

Summary

• Do not install Claude Code globally unless you have a very specific reason.
• The recommended approach is to install it locally inside each project and run it through npx or npm run.
• If you want the same convenience as a global command, add an alias, but use --no-install so it never pulls the wrong version.
• If you need a proxy, configure HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY so CLI requests remain stable.

That way you keep the convenience of typing claude, while preserving reproducibility and version consistency across projects.