Skip to content
Get packs

Guide · Open source

How to use Verdaccio: install and run a private npm registry

Updated · written with AI from the project's own documentation and checked against our catalogue data

Verdaccio is a lightweight private npm package registry that you run yourself. This guide shows you what it is for, how to install it with a package manager or Docker, and what it can do once it is running. By the end you will know whether it fits your team's need to share internal packages or test publishing locally.

Verdaccioverdaccio/verdaccio · ★ 18k · MIT

Quick start

  1. 1Check your Node.js version. Confirm you have Node.js 24 or higher for the next-9 version shown in the README.
  2. 2Install Verdaccio. Run npm install -g verdaccio@next-9, or use yarn, pnpm or Docker with the commands in the README.
  3. 3Start the registry. Run the verdaccio command from your terminal to start the local registry.
  4. 4Point npm at your registry. Configure npm to use your Verdaccio address as the registry for the packages you want to publish or install.
  5. 5Publish a test package. Publish a small internal package to confirm the registry accepts it and that you can install it back.
  6. 6Enable proxy caching. Use the uplinks setting to proxy npmjs.org so downloaded packages are cached for later installs.

What is Verdaccio and when do you need it?

Verdaccio is a simple, zero-config-required local private npm registry. It comes with its own small built-in database, so you do not need to set up a separate database just to get started.

It lets you use npm packages privately inside a company without sending your code to the public npm registry. It can also proxy other registries such as npmjs.org and cache the modules it downloads.

  • Share private packages inside a company
  • Cache npmjs.org packages so repeat installs are faster
  • Combine several registries behind one endpoint
  • Publish a locally modified version of a public package under the same name
  • Run end-to-end tests against a throwaway registry in CI

Check the Node.js requirement before you install

The README says the next-9 version requires Node.js 24 or higher. The version 6 line is maintained in the 6.x branch and requires Node.js 22 or higher.

If your machine runs an older Node.js, check the version history linked from the README before you choose a version to install.

Install Verdaccio with npm, yarn, pnpm or Docker

Pick the package manager you already use. Each command installs the next-9 version globally so the verdaccio command is available in your terminal.

The README also lists a Docker image and an official Helm chart for Kubernetes users.

  • npm: install it globally with the next-9 tag
  • yarn: use yarn global add with the same tag
  • pnpm: use pnpm i -g with the same tag
  • Docker: pull the nightly-master image
  • Helm: add the official chart repository from the README
npm install -g verdaccio@next-9 yarn global add verdaccio@next-9 pnpm i -g verdaccio@next-9 docker pull verdaccio/verdaccio:nightly-master

Use Verdaccio for private packages and proxy caching

Verdaccio covers two main jobs. For private packages, you publish your internal code to the registry and install it the same way you install public packages. For caching, Verdaccio fetches each package from npmjs.org once and keeps a copy, so later installs are faster and can still succeed if npmjs.org is briefly down for a package it already has.

You can also override a public package. If you need a patched version of a third-party package, you publish your version locally under the same name. The README points to the docs for the full steps.

  • Publish internal packages and install them like public ones
  • Reuse cached packages across several servers
  • Chain several registries and fetch from one endpoint through the uplinks feature

Use Verdaccio for end-to-end tests in CI

The README describes Verdaccio as lightweight enough to boot in a couple of seconds, which makes it practical for CI. Teams can publish test packages to a throwaway registry and install them in the same pipeline.

The README links to example repositories for GitHub Actions and to the project's e2e documentation. Many open source projects, including pnpm and Storybook, are named as users for end-to-end testing.

Extend storage with plugins

Verdaccio's built-in store is small by design. The README says community-made plugins can hook into services such as Amazon S3 and Google Cloud Storage, and you can also write your own plugin.

To build a plugin, the README points to a Yeoman generator. Install Yeoman first, then install generator-verdaccio-plugin.

npm install -g yo npm install -g generator-verdaccio-plugin

What people use it for

  • A company shares internal npm libraries across several product teams without making them public.
  • A developer tests a package's publish flow against a local registry before releasing it.
  • A CI pipeline boots Verdaccio and runs end-to-end tests against a throwaway registry.
  • A team routes installs from several registries through one internal endpoint.
  • A developer publishes a patched copy of a third-party package under the same name while waiting for an upstream fix.

Frequently asked questions

Is Verdaccio free to use?

Verdaccio is released under the MIT licence, which the repository lists. The README also asks for optional donations to support the volunteer-run project.

What Node.js version does Verdaccio need?

The README says the next-9 version requires Node.js 24 or higher. Version 6, maintained in the 6.x branch, requires Node.js 22 or higher.

How do I install Verdaccio?

Install it globally with npm install -g verdaccio@next-9, or use yarn global add or pnpm i -g with the same tag. The README also lists a Docker image, verdaccio/verdaccio:nightly-master.

Does Verdaccio need a database?

No. The README says it works out of the box with its own tiny database, so you do not need to set up a separate database to get started.

Is Verdaccio an alternative to Nexus or Artifactory?

The README lists Nexus Repository Community Edition, Artifactory and Sinopia as comparable projects. It does not compare them in detail, so check each project's documentation against your needs.

Can Verdaccio store packages in cloud storage?

The README says community-made plugins exist for services such as Amazon S3 and Google Cloud Storage, and you can write your own plugin. Plugin support details are in the Verdaccio docs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Verdaccio suits teams that want to share private npm packages, cache npmjs.org, or run a fast throwaway registry in CI, and it installs in a few commands. Pick something else if you only install public packages, need vendor-supported service with paid support, or need a large database-backed registry, since the README says the project is run by volunteers with no funding for contributions or security research.

Install options & downloads