npm-doctor

Run all default health checks for npm

$ npm doctor

$ npm doctor connection

$ npm doctor versions

$ npm doctor permissions

$ npm doctor cache

npm doctor [--json] [--registry url] [--prefix path] [--help] [--version]

--json
    Outputs the diagnostic results in JSON format, useful for programmatic consumption or scripting.

--registry url
    Specifies an alternate npm registry URL to use for network connectivity checks instead of the default.

--prefix path
    Checks write permissions for a specified alternate prefix path. This is typically where global npm packages are installed.

--help
    Displays help information for the npm doctor command, including usage and available options.

--version
    Prints the installed npm version being used by the command.

npm doctor is a powerful diagnostic tool designed to verify the health and configuration of your Node.js and npm environment. It executes a series of automated checks to pinpoint common problems that can hinder npm's functionality.

The command inspects critical aspects such as the compatibility of your Node.js and npm versions, network connectivity to the configured npm registry, and crucial read/write permissions for both the npm cache directory and the global installation prefix. It also verifies other system dependencies, like Git, if required for certain package installations.

By providing clear feedback and actionable suggestions, npm doctor helps users quickly identify and resolve underlying environmental or configuration issues, making it an invaluable utility for troubleshooting unexpected npm behavior and ensuring a smooth development workflow.

While npm doctor is effective for identifying many common environmental issues, it may not detect all possible problems, especially those related to specific project configurations, complex network proxy setups not configured for npm, or deep-seated system issues. The suggested solutions are general and might require adaptation based on your specific operating system and environment. It also requires an active internet connection to perform registry connectivity checks.

The npm doctor command performs a variety of crucial checks to ensure a healthy npm environment:
• Version Compatibility: Verifies that your installed npm and Node.js versions are compatible and up-to-date.
• Registry Connectivity: Tests the ability to connect to the configured npm registry, essential for package downloads.
• Cache Permissions: Checks read and write access to the npm cache directory, preventing issues with downloaded packages.
• Global Installation Permissions: Ensures appropriate permissions for the directory where global npm packages are installed.
• Git Availability: Confirms that Git is installed and accessible if any project dependencies require Git-based installations.

The npm doctor command was introduced in npm version 5.7.0, released in January 2018. Its primary motivation was to empower users to self-diagnose and resolve common environmental issues that frequently led to npm malfunctions, thereby reducing the burden on support and improving user experience. It marked a significant step towards making the npm CLI more self-sufficient in troubleshooting.

npm(1), npm-install(1), npm-config(1), node(1)