The npm registry is a public, collaborative space, but you often need to interact with private packages or publish your own. This requires authentication, and the standard way to manage that is with npm tokens and the .npmrc file.
Let’s see what this looks like in practice. Imagine you’re trying to install a private package:
$ npm install @my-company/private-package
npm ERR! code E401
npm ERR! 401 Unauthorized: @my-company/private-package
That 401 Unauthorized is your signal that npm doesn’t know who you are or that you don’t have permission.
To fix this, you need a token. You generate this on the npm website. Navigate to your profile settings, then "Tokens". You’ll want to create a "Read-Only" token if you only need to install packages, or a "Read and Write" token if you plan to publish. Give it a descriptive name, like "my-laptop-auth".
Once generated, you’ll see your token. Copy this immediately, because npm won’t show it to you again. It will look something like npm_2fAXXXXXXXXXXXXXXxxxxxxxxxxxxxxxxxxxxxx_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY.
Now, you need to tell npm how to use this token. This is where the .npmrc file comes in. You can create this file in two places:
- Project-specific: In the root of your project. This is great for sharing access within a team for a specific project, but it means each developer needs to set it up.
- User-specific: In your home directory (
~/.npmrc). This applies to all your npm operations on that machine.
For this example, let’s set it up for your user. Open or create the file ~/.npmrc and add the following line:
//registry.npmjs.org/:_authToken=npm_2fAXXXXXXXXXXXXXXxxxxxxxxxxxxxxxxxxxxxx_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
Explanation:
//registry.npmjs.org/: This is the registry URL. The double slash//is important, and the trailing slash/is also required. This tells npm that the following configuration applies only to requests made toregistry.npmjs.org.:_authToken=: This is the specific configuration key that npm looks for to find your authentication token for the specified registry. The colon:before_authTokenis crucial.
After saving this file, try installing your private package again:
$ npm install @my-company/private-package
added 1 package, and audited 2 packages in 1s
found 0 vulnerabilities
Success!
What if you’re working with a private registry (like npm Enterprise or Artifactory)?
The process is similar, but the registry URL in your .npmrc will change. Let’s say your private registry is at https://my-private-registry.example.com. Your .npmrc line would look like this:
//my-private-registry.example.com/:_authToken=npm_2fAXXXXXXXXXXXXXXxxxxxxxxxxxxxxxxxxxxxx_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
Notice the URL matches your private registry. If you have multiple registries, you’ll need a separate line for each.
Can I have multiple tokens in one .npmrc?
Yes. If you need to access both the public npm registry and a private one, your ~/.npmrc could look like this:
//registry.npmjs.org/:_authToken=npm_2fAXXXXXXXXXXXXXXxxxxxxxxxxxxxxxxxxxxxx_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
//my-private-registry.example.com/:_authToken=npm_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB_ZZZZZZZZZZZZZZZZZZZZZZZZ
What about scopes?
If your private packages are scoped (e.g., @my-company/private-package), npm needs to know which registry to use for that scope. You can configure this using the scope setting in .npmrc.
For a project-specific .npmrc in your project root, you’d add:
@my-company:registry=https://my-private-registry.example.com/
//my-private-registry.example.com/:_authToken=npm_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB_ZZZZZZZZZZZZZZZZZZZZZZZZ
And for a user-specific ~/.npmrc to map a scope to a registry:
@my-company:registry=https://my-private-registry.example.com/
//my-private-registry.example.com/:_authToken=npm_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB_ZZZZZZZZZZZZZZZZZZZZZZZZ
When you run npm install @my-company/private-package, npm sees the @my-company scope, checks your .npmrc for a scope configuration, finds that it maps to https://my-private-registry.example.com/, and then uses the _authToken associated with that registry URL.
Important Security Note: Never commit your .npmrc file containing tokens directly into your version control system (like Git). If you create a project-level .npmrc, add it to your .gitignore file. For user-level tokens, they are generally safe in ~/.npmrc as it’s usually excluded from version control by default.
The most common mistake people make is forgetting the leading // and the colon : before _authToken. If you see a 401 error, double-check that syntax.
Once you have tokens and .npmrc configured, the next hurdle is often understanding how npm’s dependency resolution algorithm works, especially when dealing with conflicting versions across different packages.