tools-only Installing npm Global Packages Without sudo on macOS/Linux
This guide explains how to configure npm to install global packages without requiring root permissions on macOS and Linux.
Why This Matters
By default, npm installs global packages to /usr/local, which requires sudo access. This can cause:
- Permission errors
- Security concerns from running npm with elevated privileges
- Conflicts with system-installed Node.js
Quick Setup
We provide an automated setup script that handles all the configuration for you:
Option 1: Download and run directly
curl -fsSL https://raw.githubusercontent.com/mbailey/voicemode/master/scripts/setup-npm-global.sh | bash
Option 2: Run from cloned repository
./scripts/setup-npm-global.sh
The script will:
- Create the
~/.npm-globaldirectory - Configure npm to use this directory
- Add the directory to your PATH
- Update your shell configuration file
Manual Setup
If you prefer to configure manually, follow these steps:
1. Create npm Global Directory
mkdir -p ~/.npm-global
2. Configure npm to Use This Directory
npm config set prefix '~/.npm-global'
3. Add npm Global bin to Your PATH
Add this line to your shell configuration file (~/.zshrc for Zsh or ~/.bash_profile for Bash):
export PATH="$HOME/.npm-global/bin:$PATH"
4. Reload Your Shell Configuration
# For Zsh
source ~/.zshrc
# For Bash
source ~/.bash_profile
Verification
Test by installing a package globally without sudo:
# This should work without sudo
npm install -g @google/gemini-cli
Alternative: Using Node Version Managers
For even better Node.js management, consider using:
These tools install Node.js and npm in your home directory by default, avoiding permission issues entirely.
Example with nvm:
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Install latest Node.js
nvm install node
# Global packages now install to ~/.nvm without sudo
npm install -g @google/gemini-cli
Troubleshooting
Permission Errors Still Occur
Check that your PATH is correctly set:
echo $PATH
which npm
Previously Installed Packages Not Found
You may need to reinstall global packages after changing the prefix:
npm list -g --depth=0
Reset to Default Settings
To revert these changes:
npm config delete prefix
# Remove the PATH export from your shell config file