yarn

yarn classic (1.x)

Be aware npm configurations are valid on the classic version

The classic version is able to regonize the .npmrc file, but also provides their own configuration file named .yarnrc.

To set up a registry, create a file and define a registry.

// .yarnrc
registry "http://localhost:4873"

By using this version you should enable always-auth in your configuration running:

npm config set always-auth true

yarn@1.x does not send the authorization header on yarn install if your packages requires authentication, by enabling always-auth will force yarn do it on each request.

yarn modern (>=2.x)

Yarn modern does not recognize --registry or .npmrc file anymore.

For defining a registry you must use the .yarnrc.yml located in the root of your project or global configuration.

When you publish a package the npmRegistryServer must be used. Keep in mind the publishConfig.registry in the package.json will override this configuration.

// .yarnrc.yml
npmRegistryServer: "http://localhost:4873"

unsafeHttpWhitelist:
  - localhost

unsafeHttpWhitelist is only need it if you don't use https with a valid certificate.

Using scopes is also possible and more segmented, you can define a token peer scope if is required.

npmRegistries:
  "https://registry.myverdaccio.org":
    npmAlwaysAuth: true
    npmAuthToken: <TOKEN>
npmScopes:
  my-company:
    npmRegistryServer: https://registry.myverdaccio.org
    npmPublishRegistry: https://registry.myverdaccio.org

for logging via CLi use:

yarn npm login --scope my-company

Extra registry commands

Yarn 4 ships a smaller set of registry commands than npm. There is no yarn npm ping, no yarn npm unpublish, no yarn npm deprecate and no yarn npm star, and yarn npm login only speaks the web flow.

verdaccio/yarn-plugin-npm is a set of Yarn 4 plugins that add them. They are maintained by the Verdaccio team and work against any npm-compatible registry, not only Verdaccio.

Experimental

These plugins are experimental and still on 0.0.x. Commands, flags and output may change between releases, so pin a version if you depend on them in CI.

Feedback is what moves them forward. If you try them, tell us which commands you actually needed, what behaved differently from npm, and what is still missing: open a thread in GitHub Discussions or come to Discord. Reports about what does not work are the most useful ones at this stage.

Installing

The quickest way is the importer, which downloads a plugin and registers it in your .yarnrc.yml:

yarn dlx @verdaccio/yarn-import npm-ping
yarn dlx @verdaccio/yarn-import npm-login
yarn dlx @verdaccio/yarn-import npm-unpublish
yarn dlx @verdaccio/yarn-import npm-deprecate
yarn dlx @verdaccio/yarn-import npm-star

Pin a version by appending it: yarn dlx @verdaccio/yarn-import npm-ping 0.0.1.

Check what is installed with yarn plugin list.

Requires Yarn 4.x and Node.js >= 24.

What each one adds

Plugin	Commands
npm-ping	yarn npm ping
npm-login	yarn npm login with a legacy flow
npm-unpublish	yarn npm unpublish
npm-deprecate	yarn npm deprecate
npm-star	yarn npm star, yarn npm unstar

All of them accept --registry <url>, --scope <scope> and --json.

yarn npm ping --registry http://localhost:4873
yarn npm unpublish my-package@1.0.0
yarn npm unpublish my-package --force            # every version
yarn npm deprecate my-package@"<2.0.0" "Upgrade to v2"
yarn npm deprecate my-package@1.0.0 ""           # un-deprecate
yarn npm star lodash

Logging in to a self-hosted registry

The built-in yarn npm login assumes the web flow, which is the source of the long-standing friction listed under known issues. The npm-login plugin adds --auth-type, so you can ask for the legacy username/password exchange that a self-hosted Verdaccio understands:

yarn npm login --auth-type=legacy --registry http://localhost:4873

--auth-type=auto is the default and tries the web flow first, falling back to legacy on 404/501. For CI, pass the credentials directly instead of being prompted:

yarn npm login --auth-type=legacy \
  --user "$NPM_USER" --password "$NPM_PASS" --email "$NPM_EMAIL"

Note the legacy flow creates users on registries that accept CouchDB user documents; logging in as an existing user only works when the registry exposes revision metadata without Basic authentication.

Two-factor authentication

Depends on the registry

This only applies when the operator has enabled the tfa feature flag on the Verdaccio side. It is an experimental flag, off by default, and available from 7.x; to try it, run the 9.x experimental line (verdaccio@next-9), which is where it lands first. Not recommended for production yet. See two-factor authentication.

Nothing is configured on the Yarn side.

When the registry has it enabled and your account is enrolled, Yarn handles the one-time password on its own and prompts for it:

yarn npm publish
# Provide a one-time password from your authenticator app.
# One-time password: ‹

The unpublish and deprecate plugins above also take --otp <code> for non-interactive use.

Enrolling still has to be done with npm — npm profile enable-2fa — since Yarn has no equivalent command.

Staged publishing

Not available in Yarn

Staged publishing is driven by npm stage, which is an npm command with no Yarn equivalent. Even with the stage feature flag enabled on the registry, a Yarn-based workflow cannot stage or approve versions — the registry endpoints are there, but no Yarn command calls them.

Publishing normally with yarn npm publish keeps working as usual, and is not affected by the flag.

Troubleshooting

Known issues

• yarn npm login issues, read verdaccio#1737 or yarn-berry#1848.
• yarn npm publish does not send README, read verdaccio#1905 or yarn-berry#1702.