Last updated 13 October 2026
Fix Claude Code eacces error on install
The nature of the EACCES error during global installation
The EACCES error occurs when you try to install a package globally using npm or yarn and the system denies the write request. This typically happens on macOS and Linux systems because the default directory for global packages is protected by the root user. When you run the command to install the claude command line agent, the package manager attempts to create files in folders like /usr/local/lib/node_modules. If your current user account does not have the correct permissions for these specific paths, the installation process fails immediately with a long error log ending in the EACCES code.
This is a common hurdle for developers who are setting up a new machine or using the system version of Node. It is not a bug in the coding agent itself but a configuration issue with how your local environment handles global binaries. You might see this error even if you are an administrator on your computer because the terminal session does not grant root write access to your user by default. Understanding that this is a file system permission conflict is the first step toward fixing it and getting the agent running correctly for your development projects.
The risks of using sudo with npm commands
Many developers try to fix the EACCES error by prefixing their install command with sudo. While this might allow the installation to finish, it often creates more complex problems later. Using sudo changes the ownership of the files in your npm folder to the root user. This means that when you later try to run the claude update command or use certain tools that require writing to local configuration files, you might face even more permission denied errors. The agent needs to be able to read and write to its own settings and history without requiring administrative privileges every time you type a prompt.
Running global packages with sudo can also lead to security risks and unexpected behavior in your shell. If a package has a post-install script, that script will run with full root access to your entire operating system. It is much better to fix the underlying permission issue by either changing the ownership of the folders or by moving the global installation path to a directory that your user account already owns. This ensures that the agent can function properly when it uses the Bash tool to execute commands or when it needs to update its own binary using the built-in update command.
Changing the ownership of existing global directories
One effective way to resolve the EACCES error is to reclaim ownership of the directories that npm uses for global packages. You can find the current global path by running a command to get the npm prefix. Once you know the path, you can use the chown command to change the owner to your current username. For most users on macOS, this involves targeting the lib node modules, bin, and share directories. By running a command that recursively changes ownership to your current user ID, you grant yourself the right to install the claude command without needing elevated privileges.
This method is straightforward but requires you to be careful about the paths you are modifying. You should only change ownership of folders that are specifically dedicated to node packages and binaries. After you have changed the permissions, you can try the installation again. If successful, you will be able to run the claude command from any directory in your terminal. This approach fixes the problem for all future global packages you might install, making it a permanent solution for your local development environment. It allows the agent to manage its own files and directories within the .claude folder in your home directory without hitting system-level blocks.
Configuring a custom npm prefix in the home directory
If you prefer not to change the permissions of system folders, you can tell npm to use a different directory for global installs. You can create a new folder inside your home directory, such as a hidden npm-global folder. After creating this folder, you use the npm config set prefix command to point the package manager to this new location. This ensures that every global package you install from now on is stored in a place where your user already has full write and read access. This is often considered the cleanest way to handle global binaries on a shared or managed system.
After changing the prefix, you must update your shell configuration file so the terminal knows where to find the new binaries. You will need to add the new bin path to your PATH environment variable in your .zshrc or .bashrc file. Once you restart your terminal or source the configuration file, the shell will look in your home directory for the claude command. This setup is highly reliable and prevents any future EACCES errors. It also keeps your global packages separate from the system files, which makes it easier to manage backups or migrate your setup to a new machine in the future.
Using node version managers to simplify permissions
Another popular solution is to use a node version manager like nvm or fnm. These tools do not use the system-wide installation of Node that comes with your operating system. Instead, they install Node versions directly into your home folder. Because the entire Node environment lives inside your user directory, you will never encounter an EACCES error when installing global packages. When you use a version manager, the claude command and all its dependencies are kept within a specific version's folder, which eliminates the need for root access entirely.
Switching to a version manager also allows you to test the agent against different Node versions if you ever encounter compatibility issues. Most professional developers prefer this method because it isolates the development environment from the operating system's core files. If you decide to go this route, you should uninstall the system version of Node first to avoid conflicts. Once the version manager is active, you can simply install the agent again, and it will work immediately. This approach is highly compatible with tools like adhdTerminal, which help you manage several projects at once by displaying them as tiles on a wall.
Validating the setup with the claude doctor command
Once you have successfully installed the agent, you should verify that everything is configured correctly. The agent includes a built-in utility called claude doctor that checks your installation for common issues. Running this command will tell you if the binary is in your path and if it has the necessary permissions to function. It is a vital step to ensure that the EACCES fix you applied has actually resulted in a healthy environment. If the doctor command reports any warnings, it will often provide clues about what is still missing in your shell configuration.
The doctor command also checks for connectivity and authentication status. Since the agent relies on an active session to communicate with the model, the doctor can confirm if your login is valid. If you fixed the permissions but the agent still fails to start, the output from this tool will be the most useful piece of information for troubleshooting. It verifies that the agent can reach the necessary APIs and that the local .claude settings files are accessible. Regular use of the doctor command after system updates or shell changes can help you maintain a stable coding environment without interruptions.
Organizing multiple agent sessions with adhdTerminal
After resolving your installation errors, you may find yourself running the agent in several different repositories. Keeping track of multiple terminal tabs can become difficult as your projects grow. adhdTerminal is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, not affiliated with Anthropic. It runs many Claude Code sessions side by side, each one a tile on a wall. This allows you to see the status of every active task at a glance without switching back and forth between different windows or terminal instances.
Each tile in the app shows if a session is working, waiting, or idle, and displays the last few exchanges of the conversation. This is particularly helpful when you have used a global install to set up the agent and now want to leverage its power across your entire workflow. The app even includes a free iPhone mirror so you can check on a long-running task or send a new prompt while away from your desk. It uses an end to end encrypted link to keep your code and conversations private. For a developer who has just fixed their setup and is ready to work, this tool provides a clear visual overview of all their ongoing agent activities.
Maintaining the installation with claude update
Software evolves, and you will want to keep your coding agent current to access the latest features and improvements. Because you have fixed the permission issues, you can now use the claude update command without seeing the EACCES error again. This command checks for the latest version and handles the replacement of the old binary for you. It is important to run this periodically, especially if you notice the agent behaving differently or if you see notifications about a new release in the terminal output.
If you ever find that the update command fails, you should run claude doctor again to see if your permissions have been reset by a system update or a change in your shell. Sometimes, macOS updates can reset the ownership of certain directories in /usr/local, which might require you to re-apply the chown fix. By keeping your global installation clean and your permissions mapped to your user account, you ensure that the agent remains a reliable part of your toolkit. A healthy installation is the foundation for using advanced features like MCP servers or custom subagents defined in your .claude/agents folder.
Questions people ask
Can I use the agent without a global install?
You can run the agent using npx if you want to avoid a permanent global installation on your system. However, this method is generally slower because it may need to download or verify the package each time you run it. For the best experience and fastest startup times, a global install using a version manager or a custom prefix is recommended.
How do I change the default permission mode?
You can cycle through the available permission modes like default, plan, and bypassPermissions by pressing Shift+Tab while inside an active session. If you want to set permanent permissions for specific tools like Write or Edit, you can modify the settings.json file located in the .claude directory of your project. This allows you to customize how much autonomy the agent has when modifying your files.
Where does the agent store its project instructions?
The agent looks for a file named CLAUDE.md in the root of your repository for project-specific instructions. You can also create CLAUDE.md files in subdirectories to provide context for specific parts of your codebase, or a global one at ~/.claude/CLAUDE.md for instructions that apply to every project. These files are the primary way to guide the agent's behavior and coding style.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.