fix(install): configure npm for user-local installs to avoid EACCES on Linux by MauroDruwel · Pull Request #821 · NVIDIA/NemoClaw

MauroDruwel · 2026-03-24T15:53:20Z

Summary

On standard Linux systems where Node.js is installed via the system package
manager (apt, dnf, pacman, etc.), the npm global prefix defaults to /usr or
/usr/local — directories that require root to write to. This causes npm link
to fail with EACCES: permission denied and leaves the installer with a cryptic
error message and no recovery path. This PR adds a fix_npm_permissions step
(matching the pattern already used in the upstream OpenClaw installer) that
detects the condition before npm link runs and silently redirects the prefix
to ~/.npm-global, eliminating the failure entirely without requiring sudo.

Related Issue

Related to #364
The npm EACCES permission error is one of the common installation failures
documented in that issue. This PR fixes the root cause in the installer so
users on system-managed Node.js no longer hit the error at all.

Changes

Added fix_npm_permissions() function in install.sh that:
- Runs only on Linux (no-op on macOS).
- Checks whether the current npm config get prefix is user-writable.
- If not writable (e.g. /usr, /usr/local), redirects the npm global
  prefix to ~/.npm-global.
- Appends export PATH="$HOME/.npm-global/bin:$PATH" to ~/.bashrc and
  ~/.zshrc (only if the file exists and the entry is not already present).
- Exports the updated PATH for the current installer session.
Called fix_npm_permissions in main() immediately before install_nemoclaw
so the correct prefix is always in place before npm link runs.

Type of Change

Code change for a new feature, bug fix, or refactor.

Testing

npx prek run --all-files passes (or equivalently make check).
npm test passes.
make docs builds without warnings. (for doc-only changes)

Manual reproduction:

# Reproduce on Ubuntu 22.04 with system Node.js (npm prefix = /usr)
node --version   # v20.x via apt
npm config get prefix  # /usr  ← not writable without root

curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
# Before this PR: fails with EACCES at "Linking NemoClaw CLI"
# After  this PR: installer prints "[INFO] npm global prefix '/usr' is not
#                 writable — configuring user-local installs" and completes
#                 successfully.

Tested on:

OS	Node.js source	npm prefix before	Result
Ubuntu 22.04	`apt`	`/usr`	✅ Fixed — prefix redirected to `~/.npm-global`
Ubuntu 24.04	`nvm`	`~/.nvm/…` (writable)	✅ No change in behavior
macOS 14	`brew`	`/opt/homebrew`	✅ No-op (Linux-only guard)

Checklist

General

I have read and followed the contributing guide.
I have read and followed the style guide. (for doc-only changes)

Code Changes

Formatters applied — npx prek run --all-files auto-fixes formatting (or make format for targeted runs).
Tests added or updated for new or changed behavior.
No secrets, API keys, or credentials committed.
Doc pages updated for any user-facing behavior changes (new commands, changed defaults, new features, bug fixes that contradict existing docs).

Doc Changes

Follows the style guide.
New pages include SPDX license header and frontmatter, if creating a new page.
Cross-references and links verified.

Prior art / comparison

Two earlier PRs attempted to fix this:

	PR #91	PR #517	This PR
Approach	`sudo npm link`	Permission check → retry with `sudo`	Prefix redirect to `~/.npm-global`
Works without root	❌	❌	✅
Works in CI / Docker	❌ (sudo prompts / missing)	❌	✅
Elevated privileges	✅ required	✅ required	❌ not needed
Side-effects	Writes to system paths	Writes to system paths	Writes only to `~/`
Upstream precedent	—	—	✅ Same pattern as OpenClaw installer

This approach is the one recommended in NemoClaw's own troubleshooting docs
and is already used verbatim in the upstream OpenClaw installer. It avoids
elevated privileges entirely, works in any non-interactive environment, and
has no impact on users who already have a writable prefix (nvm, fnm, Volta,
or a manually configured ~/.npm-global).

Summary by CodeRabbit

Bug Fixes
- Installer now detects and resolves npm global permission issues on Linux by configuring a user-writable npm location, updating the PATH in common shell profiles when needed, and applying the adjusted environment before installing the CLI. This reduces installation failures and ensures globally installed tools are immediately usable after setup.

…on issues on Linux

coderabbitai · 2026-03-24T15:53:37Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5331a7d2-c365-4888-8393-6f3b6ad3e121

📥 Commits

Reviewing files that changed from the base of the PR and between 53e25ce and bbed71a.

📒 Files selected for processing (1)

install.sh

🚧 Files skipped from review as they are similar to previous changes (1)

install.sh

📝 Walkthrough

Walkthrough

Added a Linux-only fix_npm_permissions() to install.sh that ensures npm global operations use a user-writable prefix (~/.npm-global), updates npm’s prefix and PATH, and appends PATH exports to ~/.bashrc/~/.zshrc when needed. main() now calls this before install_nemoclaw.

Changes

Cohort / File(s)	Summary
NPM Permissions Fix `install.sh`	Added `fix_npm_permissions()` (Linux-only) to check `npm config get prefix` writability, create `~/.npm-global` if needed, set npm prefix, prepend `~/.npm-global/bin` to PATH for the current process, and append an "Added by NemoClaw installer" PATH export block to `~/.bashrc` and `~/.zshrc` when those files exist and don't already reference `.npm-global`. Updated `main()` to call `fix_npm_permissions` before `install_nemoclaw`.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Installer as "install.sh"
    participant npm as "npm config"
    participant Shell as "shell rc files"

    User->>Installer: run install script
    Installer->>npm: npm config get prefix
    alt prefix not writable
        Installer->>Installer: mkdir ~/.npm-global
        Installer->>npm: npm config set prefix ~/.npm-global
        Installer->>Installer: export PATH=~/.npm-global/bin:$PATH (current proc)
        Installer->>Shell: append export block to ~/.bashrc / ~/.zshrc if missing
    else prefix writable
        Installer->>Installer: no-op
    end
    Installer->>Installer: call install_nemoclaw (uses adjusted env)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped in to tweak your npm trail,
Made ~/.npm-global safe and hale,
PATH set right, no more sudo chase,
Installer hums with calmer pace —
Hooray for tidy package sail! 🥕✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: configuring npm for user-local installs to avoid EACCES errors on Linux, which directly matches the core functionality added in the PR.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

…guration files

wscurran · 2026-03-24T21:32:40Z

✨ Thanks for submitting this PR, it addresses a bug that could cause issues during installation on Linux systems.

…n Linux (NVIDIA#821) * fix(install): configure npm for user-local installs to avoid permission issues on Linux * fix(install): correct formatting in path addition to user shell configuration files --------- Co-authored-by: Carlos Villela <cvillela@nvidia.com>

…n Linux (#821) * fix(install): configure npm for user-local installs to avoid permission issues on Linux * fix(install): correct formatting in path addition to user shell configuration files --------- Co-authored-by: Carlos Villela <cvillela@nvidia.com>

…n Linux (NVIDIA#821) * fix(install): configure npm for user-local installs to avoid permission issues on Linux * fix(install): correct formatting in path addition to user shell configuration files --------- Co-authored-by: Carlos Villela <cvillela@nvidia.com>

fix(install): configure npm for user-local installs to avoid permissi…

2c4d4b2

…on issues on Linux

MauroDruwel changed the title ~~fix(install): configure npm for user-local installs to avoid permissi…~~ fix(install): configure npm for user-local installs to avoid EACCES on Linux Mar 24, 2026

This was referenced Mar 24, 2026

fix: use sudo for npm installation if needed #91

Closed

fix(install): check permissions before npm link #517

Closed

MauroDruwel and others added 2 commits March 24, 2026 17:09

fix(install): correct formatting in path addition to user shell confi…

005c554

…guration files

Merge branch 'main' into main

d21a314

wscurran added bug Something fails against expected or documented behavior fix platform: ubuntu Affects Ubuntu Linux environments labels Mar 24, 2026

MauroDruwel and others added 3 commits March 25, 2026 12:23

Merge branch 'NVIDIA:main' into main

8259cb9

Merge branch 'NVIDIA:main' into main

53e25ce

Merge branch 'main' into main

bbed71a

cv approved these changes Mar 30, 2026

View reviewed changes

cv merged commit bdd61da into NVIDIA:main Mar 30, 2026
4 of 6 checks passed

ericksoa mentioned this pull request Apr 5, 2026

installation fails with default nodejs package path #569

Closed

2 tasks

wscurran added bug-fix PR fixes a bug or regression and removed priority: medium bug Something fails against expected or documented behavior labels Jun 3, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(install): configure npm for user-local installs to avoid EACCES on Linux#821

fix(install): configure npm for user-local installs to avoid EACCES on Linux#821
cv merged 6 commits into
NVIDIA:mainfrom
MauroDruwel:main

MauroDruwel commented Mar 24, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Mar 24, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

wscurran commented Mar 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

MauroDruwel commented Mar 24, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Type of Change

Testing

Checklist

General

Code Changes

Doc Changes

Prior art / comparison

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

❌ Failed checks (1 warning)

Uh oh!

wscurran commented Mar 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MauroDruwel commented Mar 24, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Mar 24, 2026 •

edited

Loading