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