How to Fix Salesforce CLI NPM Installation Errors

William Watson · 18 min · Updated Jan 26, 2026

Why is my Salesforce CLI installation failing?

Salesforce CLI installation via npm fails for several common reasons: permission errors, conflicting packages, Windows PowerShell restrictions, or network issues. This guide covers each error with step-by-step fixes.

Quick check: Are you installing the correct package? Use @salesforce/cli, not the deprecated sfdx-cli. Run: npm install @salesforce/cli --global

How do I fix “EACCES: permission denied” errors?

The EACCES error occurs when npm tries to write to directories your user doesn’t own. This typically happens with default Node.js installations.

# Error: EACCES: permission denied, access '/usr/local/lib/node_modules'
# npm ERR! code EACCES

Don’t use sudo – it creates more permission problems. Instead, use one of these solutions:

Node Version Manager installs Node.js in your home directory, avoiding permission issues entirely. This is Salesforce’s recommended approach.

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart your terminal, then install Node.js
nvm install --lts
nvm use --lts

# Now install Salesforce CLI without permission issues
npm install @salesforce/cli --global

Solution 2: Change npm’s default directory

If you can’t use nvm, configure npm to use a directory in your home folder:

# Create a directory for global packages
mkdir ~/.npm-global

# Configure npm to use it
npm config set prefix '~/.npm-global'

# Add to your PATH (add this to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Restart terminal and install
npm install @salesforce/cli --global

Solution 3: Fix existing directory ownership

If you’ve already used sudo and have mixed permissions:

# Fix npm directories (macOS/Linux)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Fix Salesforce CLI directory if it exists
sudo chown -R $(whoami) ~/.sf

How do I fix “sf: command not found” after installation?

If the installation succeeded but sf or sfdx commands aren’t recognised, your PATH doesn’t include npm’s global bin directory.

# sf: command not found
# sfdx: command not found

Check where npm installed the CLI

npm list -g --depth 0

If you see @salesforce/[email protected] in the output, the CLI is installed but not in your PATH.

Find and add the npm bin directory

# Find npm's global bin directory
npm config get prefix

# This returns something like /usr/local or ~/.npm-global
# Add /bin to that path and add it to your shell profile

Add to your ~/.bashrc, ~/.zshrc, or shell profile:

# If npm prefix is /usr/local
export PATH=/usr/local/bin:$PATH

# If npm prefix is ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Then restart your terminal or run source ~/.bashrc.

How do I fix PowerShell execution policy errors on Windows?

Windows PowerShell blocks script execution by default, causing this error when running npm or Salesforce CLI:

# sf.ps1 cannot be loaded because running scripts is disabled on this system
# npm.ps1 cannot be loaded because running scripts is disabled on this system

Solution: Change the execution policy

Open PowerShell as Administrator and run:

# Check current policy
Get-ExecutionPolicy

# Set to RemoteSigned for current user (recommended)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

# Confirm with 'Y' when prompted

This allows locally-created scripts to run while still blocking unsigned remote scripts.

Alternative: Use Command Prompt

If you can’t change the execution policy, use Command Prompt (cmd.exe) instead of PowerShell for npm and sf commands.

How do I fix conflicting sfdx-cli and @salesforce/cli installations?

If you have both the old sfdx-cli package and new @salesforce/cli installed, you’ll get conflicts:

# npm ERR! EEXIST: file already exists
# The "sfdx" command is already installed by another package

Both packages try to create the sfdx command, causing the conflict.

Solution: Uninstall the old package first

# Remove the deprecated sfdx-cli package
npm uninstall sfdx-cli --global

# Clear npm cache
npm cache clean --force

# Install the current package
npm install @salesforce/cli --global

# Verify
sf --version

For CI/CD pipelines

If your CI scripts install both packages, update them to use only @salesforce/cli:

# Old (don't use)
- npm install sfdx-cli --global

# New (correct)
- npm install @salesforce/cli --global

How do I fix ETIMEDOUT or ECONNREFUSED errors?

Network errors during installation usually indicate proxy issues or network restrictions:

# npm ERR! code ETIMEDOUT
# npm ERR! code ECONNREFUSED
# npm ERR! network request failed

Solution 1: Check proxy settings

If you’re behind a corporate proxy:

# Set proxy (replace with your proxy URL)
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Or remove incorrect proxy settings
npm config delete proxy
npm config delete https-proxy

Solution 2: Clear cache and retry

npm cache clean --force
npm install @salesforce/cli --global

Solution 3: Use a different registry

Try the npm mirror if the main registry is blocked:

npm install @salesforce/cli --global --registry https://registry.npmmirror.com

What is the difference between sf and sfdx commands?

Both commands work identically. When you install @salesforce/cli, you get both sf and sfdx as entry points. The sfdx command is an alias maintained for backward compatibility.

# These are equivalent
sf org list
sfdx org list

# Both command styles work
sf project deploy start
sfdx force:source:deploy  # deprecated style, but still works

For new projects: Use sf commands with the newer syntax (spaces instead of colons).

For existing scripts: Your sfdx commands continue to work without changes.

How do I verify my installation is working?

Run these commands to confirm everything is set up correctly:

# Check CLI version
sf --version

# Run diagnostics
sf doctor

# List globally installed npm packages
npm list -g --depth 0 | grep salesforce

You should see output like:

@salesforce/cli/2.x.x darwin-arm64 node-v20.x.x

How do I pin a specific CLI version for CI/CD?

For reproducible builds, lock your team to a specific version:

# Install specific version globally
npm install @salesforce/[email protected] --global

# Or install locally in your project
npm install @salesforce/[email protected] --save-dev

For local installation, run commands via npx:

npx sf org list
npx sf project deploy start

Disable auto-updates in CI

Salesforce CLI auto-updates by default. Disable this in CI environments:

# Set environment variable
export SF_AUTOUPDATE_DISABLE=true

# Then run your commands
sf project deploy start

GitHub Actions example

Here’s a working GitHub Actions workflow for Salesforce CI/CD:

name: Salesforce Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Salesforce CLI
        run: npm install @salesforce/cli --global

      - name: Verify installation
        run: sf --version

      - name: Authenticate
        run: |
          echo "${{ secrets.SFDX_AUTH_URL }}" > auth.txt
          sf org login sfdx-url --sfdx-url-file auth.txt --alias target-org

      - name: Deploy
        run: sf project deploy start --target-org target-org

Still having issues?

If none of these solutions work:

  1. Check Node.js version: Salesforce CLI requires Node.js 20.9 or higher. Run node --version to check.
  2. Try the standalone installer: Download from Salesforce CLI if npm continues to fail.
  3. Report bugs: File issues at the Salesforce CLI GitHub repo.

For basic installation steps, see our guide on How to Install Salesforce CLI with NPM.