[DOCS] Inconsistent installation instructions: Troubleshooting guide recommends deprecated NPM method instead of native installer

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/troubleshooting

Section/Topic

The section titled "Linux and Mac installation issues: permission or command not found errors".

Current Documentation

The troubleshooting documentation currently advises:

"When installing Claude Code with npm, PATH problems may prevent access to claude. You may also encounter permission errors if your npm global prefix is not user writable..."

It then suggests running:

npm install -g @anthropic-ai/claude-code --force --no-os-check

What's Wrong or Missing?

The workflow in the troubleshooting guide contradicts the main setup guide.

According to the Setup page (https://code.claude.com/docs/en/setup), NPM installation is explicitly deprecated:

"NPM installation is deprecated. Use the native installation method when possible."

However, the troubleshooting guide presents the NPM command as a standard solution for permission errors without mentioning that this method is deprecated or offering the native installer (which inherently avoids many NPM permission issues) as the primary fix. This confuses the user by directing them to use an installation method the main documentation advises against.

Suggested Improvement

The troubleshooting section for Linux/Mac installation issues should be updated to prioritize the Native Installer, as it resolves the NPM permission/path issues by bypassing NPM entirely.

Suggested changes:

1. Update the "Linux and Mac installation issues" section to recommend switching to the Native Installer as the primary fix.
2. Provide the native install command: curl -fsSL https://claude.ai/install.sh | bash
3. Explicitly label the NPM troubleshooting steps as "Legacy/Deprecated" or remove them if they are no longer supported.

Impact

High - Prevents users from using a feature

Additional Context

• Conflict Source:
• Troubleshooting Guide: https://code.claude.com/docs/en/troubleshooting#linux-and-mac-installation-issues-permission-or-command-not-found-errors
• Setup Guide (Deprecation Notice): https://code.claude.com/docs/en/setup#npm-installation-deprecated