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