10 January, 20244 minute read

How to install private npm packages

If you’ve got an error which looks like the one below, this article will help you resolve it.

$ npm add @acme/a-private-packagenpm ERR! code E404npm ERR! 404 Not Found - GET https://registry.npmjs.org/@acme%2fa-private-package - Not foundnpm ERR! 404npm ERR! 404  '@acme/a-private-package@*' is not in this registry.npm ERR! 404npm ERR! 404 Note that you can also install from anpm ERR! 404 tarball, folder, http url, or git url. npm ERR! A complete log of this run can be found in:npm ERR!     /Users/sophia/.npm/_logs/2024-01-07T00_58_28_355Z-debug-0.log

Note that while this tutorial is being written as though you’re using npm for your package manager, the instructions will work equally well for pnpm and yarn. Both of the alternate package managers support reading configuration from .npmrc, which is the file we need to edit in order to fix the error.

How to

  1. Get your hands on an npm access token. They look like npm_<random-string>. Depending on your company, the way you’ll get one will differ:
    • You might just get handed a shared access token by your platform team, onboarding buddy, or similar.
    • There might be a shared access token in your team’s password manager.
    • There might be credentials for a shared npm account1 in your team’s password manager. Sign in to this account, and create an access token.
    • You might get your personal npm account added to your company’s organization. After getting added to the organization, go ahead and create an access token.


If you end up needing to create your own access token, then carefully consider what permissions you’ll need. Creating a read-only token for day-to-day use is likely the smart move.

  1. Now that you have an access token, you’ll need to configure npm to use it.
  2. Open up (or create) a .npmrc file inside your home directory.
    • If you aren’t sure where that is, then you can open up a terminal and type open $HOME to get there.
  3. Inside that file, you’ll want to put in a line like the following: //registry.npmjs.org/:_authToken=<your access token>.
  4. You’re done! You should now be able to install that private package without errors.


My package is stored in a private registry (e.g. GitHub Packages) and not npm. What do I do?

The .npmrc file lets you configure different registries. This tells your package manager where to fetch packages from.

If you want to use your custom registry for all packages (e.g. you are using something like Verdaccio or Gemfury) then your .npmrc will look like this:

Click to copy
registry=https://npm-proxy.fury.io/<access token>/<username>/

If you want to keep using the npm registry for public packages and only want to use your custom registry for private packages, then you can do so as long as your private packages are scoped (think @acme/logger vs. logger). Here’s what you’ll want your .npmrc to look like:

Click to copy
@acme:registry=//npm.fury.io/<username>/:_authToken=<access token>

Keep in mind that if your custom registry is being used solely for private packages and isn’t an npm proxy then your npm access token may not work with it. Gemfury, for instance, has its own access token system you’ll need to use in this case.

Each registry will have its own URL, so you’ll need to do some digging. The query “«service» npm registry url” is a good starting point if you are unsure what you are looking for.

I need to install packages from multiple organizations, how can I do this?

If all organizations work by adding your personal account to the npm organization, then you can simply create a personal access token scoped to both organizations.

If you’re in a situation where your organizations are using shared npm accounts, or your organizations aren’t comfortable with you using your personal account then you can still get things working.

While it isn’t possible to have multiple access tokens configured for the same registry inside your global .npmrc file, it is possible to emulate it with local files.

Node package managers load the .npmrc file from a few different locations, and one of the locations is the current working directory.

Therefore it is possible for you to create .npmrc files in each project’s directory, each containing the access key appropriate for that project:

Click to copy
# organization A~/Code/foo-logger/.npmrc # organization B~/Code/acme-logger/.npmrc

I have my npm token in a .env file and it’s not working. What gives?

While .env files are supported by a lot of different tools, they are not a universal standard and they don’t automatically work with everything. Individual tools need to implement reading and loading .env files, and a lot of tools don’t do this.

None of the Node package managers (npm, pnpm, or yarn) implement this support for .env files. When you run npm install your .env file might as well not exist.

If you want to use .env files with npm, you can install a tool like direnv which hooks in to your shell and automatically loads the contents of relevant .env files whenever you run a command.

  1. Naturally, account sharing like this is against the npm terms of service. But that may or may not stop your employer from trying to save some cost on their subscriptions 🙂

Don't want to miss out on new posts?

Join 100+ fellow engineers who subscribe for software insights, technical deep-dives, and valuable advice.

Get in touch 👋

If you're working on an innovative web or AI software product, then I'd love to hear about it. If we both see value in working together, we can move forward. And if not—we both had a nice chat and have a new connection.
Send me an email at hello@sophiabits.com