Skip to searchSkip to content
npm Docs
npmjs.comStatusSupport

package-spec

Package name specifier

Select CLI Version:

See DetailsTable of contents

Description

Commands like npm install and the dependency sections in the package.json use a package name specifier. This can be many different things that all refer to a "package". Examples include a package name, git url, tarball, or local directory. These will generally be referred to as in the help output for the npm commands that use this package name specifier.

Package name

  • [<@scope>/]
  • [<@scope>/]@
  • [<@scope>/]@
  • [<@scope>/]@

Refers to a package by name, with or without a scope, and optionally tag, version, or version range. This is typically used in combination with the registry config to refer to a package in a registry.

Examples:

Aliases

  • @npm:

Primarily used by commands like npm install and in the dependency sections in the package.json, this refers to a package by an alias. The is the name of the package as it is reified in the node_modules folder, and the refers to a package name as found in the configured registry.

See Package name above for more info on referring to a package by name, and registry for configuring which registry is used when referring to a package by name.

Examples:

  • semver:@npm:@npmcli/semver-with-patch
  • semver:@npm:[email protected]
  • semver:@npm:semver@legacy

Folders

This refers to a package on the local filesystem. Specifically this is a folder with a package.json file in it. This should always be prefixed with a / or ./ (or your OS equivalent) to reduce confusion. npm currently will parse a string with more than one / in it as a folder, but this is legacy behavior that may be removed in a future version.

Examples:

  • ./my-package
  • /opt/npm/my-package

Tarballs

Examples:

  • ./my-package.tgz
  • https://registry.npmjs.org/semver/-/semver-1.0.0.tgz

Refers to a package in a tarball format, either on the local filesystem or remotely via url. This is the format that packages exist in when uploaded to a registry.

git urls

  • /

Refers to a package in a git repo. This can be a full git url, git shorthand, or a username/package on GitHub. You can specify a git tag, branch, or other git ref by appending #ref.

Examples:

See also

npm-package-arg scope config

Edit this page on GitHub
1 contributorlukekarrys
Last edited by lukekarrys on October 26, 2022

Table of contents