1---
2section: using-npm
3title: scope
4description: Scoped packages
5---
6# scope(7)
7
8## Scoped packages
9
10### Description
11
12All npm packages have a name. Some package names also have a scope. A scope
13follows the usual rules for package names (URL-safe characters, no leading dots
14or underscores). When used in package names, scopes are preceded by an `@` symbol
15and followed by a slash, e.g.
16
17```bash
18@somescope/somepackagename
19```
20
21Scopes are a way of grouping related packages together, and also affect a few
22things about the way npm treats the package.
23
24Each npm user/organization has their own scope, and only you can add packages
25in your scope. This means you don't have to worry about someone taking your
26package name ahead of you. Thus it is also a good way to signal official packages
27for organizations.
28
29Scoped packages can be published and installed as of `npm@2` and are supported
30by the primary npm registry. Unscoped packages can depend on scoped packages and
31vice versa. The npm client is backwards-compatible with unscoped registries,
32so it can be used to work with scoped and unscoped registries at the same time.
33
34### Installing scoped packages
35
36Scoped packages are installed to a sub-folder of the regular installation
37folder, e.g. if your other packages are installed in `node_modules/packagename`,
38scoped modules will be installed in `node_modules/@myorg/packagename`. The scope
39folder (`@myorg`) is simply the name of the scope preceded by an `@` symbol, and can
40contain any number of scoped packages.
41
42A scoped package is installed by referencing it by name, preceded by an
43`@` symbol, in `npm install`:
44
45```bash
46npm install @myorg/mypackage
47```
48
49Or in `package.json`:
50
51```json
52"dependencies": {
53  "@myorg/mypackage": "^1.3.0"
54}
55```
56
57Note that if the `@` symbol is omitted, in either case, npm will instead attempt to
58install from GitHub; see [`npm install`](/cli-commands/npm-install).
59
60### Requiring scoped packages
61
62Because scoped packages are installed into a scope folder, you have to
63include the name of the scope when requiring them in your code, e.g.
64
65```javascript
66require('@myorg/mypackage')
67```
68
69There is nothing special about the way Node treats scope folders. This
70simply requires the `mypackage` module in the folder named `@myorg`.
71
72### Publishing scoped packages
73
74Scoped packages can be published from the CLI as of `npm@2` and can be
75published to any registry that supports them, including the primary npm
76registry.
77
78(As of 2015-04-19, and with npm 2.0 or better, the primary npm registry
79**does** support scoped packages.)
80
81If you wish, you may associate a scope with a registry; see below.
82
83#### Publishing public scoped packages to the primary npm registry
84
85To publish a public scoped package, you must specify `--access public` with
86the initial publication. This will publish the package and set access
87to `public` as if you had run `npm access public` after publishing.
88
89#### Publishing private scoped packages to the npm registry
90
91To publish a private scoped package to the npm registry, you must have
92an [npm Private Modules](https://docs.npmjs.com/private-modules/intro)
93account.
94
95You can then publish the module with `npm publish` or `npm publish
96--access restricted`, and it will be present in the npm registry, with
97restricted access. You can then change the access permissions, if
98desired, with `npm access` or on the npmjs.com website.
99
100### Associating a scope with a registry
101
102Scopes can be associated with a separate registry. This allows you to
103seamlessly use a mix of packages from the primary npm registry and one or more
104private registries, such as npm Enterprise.
105
106You can associate a scope with a registry at login, e.g.
107
108```bash
109npm login --registry=http://reg.example.com --scope=@myco
110```
111
112Scopes have a many-to-one relationship with registries: one registry can
113host multiple scopes, but a scope only ever points to one registry.
114
115You can also associate a scope with a registry using `npm config`:
116
117```bash
118npm config set @myco:registry http://reg.example.com
119```
120
121Once a scope is associated with a registry, any `npm install` for a package
122with that scope will request packages from that registry instead. Any
123`npm publish` for a package name that contains the scope will be published to
124that registry instead.
125
126### See also
127
128* [npm install](/cli-commands/npm-install)
129* [npm publish](/cli-commands/npm-publish)
130* [npm access](/cli-commands/npm-access)
131* [npm registry](/using-npm/registry)
132