How to Fix Salesforce CLI NPM Installation Errors

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

Already have the error on screen? Each line below gives the error class, the first check its section makes, and a link to that section.

EACCES: permission denied. First check which directory npm is trying to write to: the error names it, and your user does not own it. Do not reach for sudo. Jump to the EACCES fix.
sf: command not found. First run npm list -g --depth 0. If @salesforce/cli is listed, the CLI is installed and your PATH is missing npm’s global bin directory. Jump to the command not found fix.
PowerShell execution policy. First run Get-ExecutionPolicy in PowerShell opened as Administrator and read the current policy. Jump to the PowerShell fix.
sfdx-cli and @salesforce/cli conflict. First check whether both packages are installed: the EEXIST error says the sfdx command is already installed by another package. Jump to the conflict fix.
ETIMEDOUT and ECONNREFUSED. First check npm’s proxy settings: set them if you are behind a corporate proxy, or delete a wrong entry. Jump to the network errors fix.

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:

Solution 1: Use nvm (Recommended)

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

After it works: three things to do before you move on.

Pin the version your team and CI install, so a new release does not change behaviour under you: How do I pin a specific CLI version for CI/CD? below.

Keep npm managing the install the way the setup guide recommends: nvm, a local pinned install for CI, sf over sfdx, and sf doctor when something feels off. See its best practices.

Confirm the version, the executable location and plugin health in the shell your scripts use, before you touch auth or deploys: the DevOps playbook’s post-install configuration.

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:

Check Node.js version: Salesforce CLI requires Node.js 20.9 or higher. Run node --version to check.
Try the standalone installer: Download from Salesforce CLI if npm continues to fail.
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.