npm package name checker and rules
A brand claims its name on npm as a package name, or as an organization scope such as @yourname. Our check looks up the package name. How our checks work
What can an npm package name contain?
Lowercase letters, numbers, hyphens, periods and underscores, up to 214 characters including any scope. The name becomes part of a URL, so it can't hold characters that aren't URL-safe.
| Character | Allowed? | Where |
|---|---|---|
| Lowercase a to z | Yes | Anywhere |
| Capital letters | No | Not in new packages |
| Numbers 0 to 9 | Yes | Anywhere |
| Hyphen (-) | Yes | Anywhere |
| Period (.) and underscore (_) | Yes | Not first, unless the name has a scope |
| Spaces and ~ ) ( ' ! * | No |
A name also can't match a Node.js core module, such as http or stream, or a reserved name such as node_modules.[1, 5]
Why is my npm name blocked when nobody uses it?
It's too close to an existing package. npm removes punctuation from a new name and compares it with existing names: because react-native exists, nobody can publish reactnative, react_native or react.native. Our check looks up the exact name, so it can't spot this; if your name has punctuation, check it without the punctuation too.
The name guidelines also ask that unscoped names not be spelled like another package or confuse people about who made it. The fix is your scope: @yourname/package.[2, 9]
What is an npm scope?
A namespace that matches your user or organization name, written @yourname/package. Inside it you can use any package name, even one someone else has taken unscoped.
| Fact | Detail |
|---|---|
| You get one | Every user and organization is granted a scope matching its name |
| Organizations | The organization name is also its scope |
| Private by default | Scoped packages need a flag at publishing to be public |
How do you claim your name on npm?
Create an organization to hold your scope, then publish a package to hold the plain name.
- Check the name above, with GitHub and the .com.
- Create an npm account and sign in.
- Click your profile picture, then Add an Organization. Enter the name and pick the free plan to hold @yourname.
- Publish a package with the plain name to hold it unscoped too.[7]
How much does npm cost?
Nothing for public packages. Private packages need a paid account.
| Plan | Price | Includes |
|---|---|---|
| Free organization | $0 | Unlimited public packages |
| Paid organization | $7 per member a month | Private packages for members |
What should you know before you claim an npm name?
Names are first come, first served, and npm can remove names held without real use.
| Fact | What it means |
|---|---|
| First come, first served | Package, user and organization names go to whoever claims them first |
| No squatting | A package with no genuine function, or an organization with no packages in a reasonable time, counts as squatting |
| Paid organizations | Never treated as squatting |
| Unpublishing | Allowed within 72 hours; after removing every version, you wait 24 hours to publish again |
| Version numbers | Once used, a version number can never be used again |
What if someone already has your npm name?
Names aren't handed over on request. For a trademark claim, file a Trademark Policy Violation Report through GitHub's support form, since npm follows GitHub's policy. A username is very unlikely to change hands.[4]
Which platforms should you claim with npm?
GitHub, PyPI, X, the .com and the .dev.
Checks npm, GitHub, PyPI, X, the .com and the .dev in one search.
Sources (9)
- Primarynpm Docs: package.json
- Primarynpm Docs: Package name guidelines
- Primarynpm Docs: About scopes
- Primarynpm Docs: npm disputes policy
- Primarynpm on GitHub: validate-npm-package-name
- Primarynpm Docs: Unpublish policy
- Primarynpm Docs: Creating an organization
- Primarynpm Docs: Upgrading to a paid organization plan
- Primarynpm Blog: New package moniker rules