All npm packages have a name. Some package names also have a scope. A scope
follows the usual rules for package names (URL-safe characters, no leading dots
or underscores). When used in package names, scopes are preceded by an
and followed by a slash, e.g.
Scopes are a way of grouping related packages together, and also affect a few things about the way npm treats the package.
Each npm user/organization has their own scope, and only you can add packages in your scope. This means you don't have to worry about someone taking your package name ahead of you. Thus it is also a good way to signal official packages for organizations.
Scoped packages can be published and installed as of
npm@2 and are supported
by the primary npm registry. Unscoped packages can depend on scoped packages and
vice versa. The npm client is backwards-compatible with unscoped registries,
so it can be used to work with scoped and unscoped registries at the same time.
Scoped packages are installed to a sub-folder of the regular installation
folder, e.g. if your other packages are installed in
scoped modules will be installed in
node_modules/@myorg/packagename. The scope
@myorg) is simply the name of the scope preceded by an
@ symbol, and can
contain any number of scoped packages.
A scoped package is installed by referencing it by name, preceded by an
@ symbol, in
npm install @myorg/mypackage
Note that if the
@ symbol is omitted, in either case, npm will instead attempt to
install from GitHub; see
Because scoped packages are installed into a scope folder, you have to include the name of the scope when requiring them in your code, e.g.
There is nothing special about the way Node treats scope folders. This
simply requires the
mypackage module in the folder named
Scoped packages can be published from the CLI as of
npm@2 and can be
published to any registry that supports them, including the primary npm
(As of 2015-04-19, and with npm 2.0 or better, the primary npm registry does support scoped packages.)
If you wish, you may associate a scope with a registry; see below.
To publish a public scoped package, you must specify
--access public with
the initial publication. This will publish the package and set access
public as if you had run
npm access public after publishing.
To publish a private scoped package to the npm registry, you must have an npm Private Modules account.
You can then publish the module with
npm publish or
--access restricted, and it will be present in the npm registry, with
restricted access. You can then change the access permissions, if
npm access or on the npmjs.com website.
Scopes can be associated with a separate registry. This allows you to seamlessly use a mix of packages from the primary npm registry and one or more private registries, such as npm Enterprise.
You can associate a scope with a registry at login, e.g.
npm login --registry=http://reg.example.com --scope=@myco
Scopes have a many-to-one relationship with registries: one registry can host multiple scopes, but a scope only ever points to one registry.
You can also associate a scope with a registry using
npm config set @myco:registry http://reg.example.com
Once a scope is associated with a registry, any
npm install for a package
with that scope will request packages from that registry instead. Any
npm publish for a package name that contains the scope will be published to
that registry instead.