Configuring NPM for use with GitHub Package Registry

You can configure npm to publish packages to GitHub Package Registry and to use packages stored on GitHub Package Registry as dependencies in an npm project.

GitHub Package Registry is currently available in limited public beta. You should avoid using GitHub Package Registry for high-value workflows and content during the beta period. For more information, see "About GitHub Package Registry."

In this article

Authenticating to GitHub Package Registry

You must use a personal access token with the read:packages and write:packages scopes to publish and delete public packages in the GitHub Package Registry with npm. Your personal access token must also have the repo scope when the repository is private. For more information, see "Creating a personal access token for the command line."

You can configure npm to use your token when pushing new packages by editing your ~/.npmrc file or creating one if it doesn't exist. It should look similar to the example below.

//npm.pkg.github.com/:_authToken=PERSONAL-ACCESS-TOKEN

You can also log in with npm using your username and personal access token.

$ npm login --registry=https://npm.pkg.github.com
> Username: USERNAME> Password: TOKEN> Email: PUBLIC EMAIL ADDRESS

You can also use a GITHUB_TOKEN to publish and consume packages in the GitHub Package Registry in a GitHub Actions workflow without storing and managing a personal access token. For more information about GITHUB_TOKEN, see "GITHUB_TOKEN secret."

You can use a script to inject your GITHUB_TOKEN into the appropriate configuration file for GitHub Package Registry. Add GitHub Package Registry as an alernative registry or repository in the configuration file for the package client, as well as your GitHub username and a personal access token with the appropriate scopes. The exact steps for creating a configuration file vary by package type.

Publishing a package

You can set up the scope mapping for your project using either a local .npmrc file in the project or using the publishConfig option in the package.json. You can also publish multiple packages to the same GitHub repository.

Note: GitHub Package Registry only supports scoped NPM packages. Scoped packages have names with the format of @owner/name. Scoped packages always begin with an @ symbol. You may need to update the name in your package.json to use the scoped name. For example, "name": "@codertocat/hello-world-npm".

Because upper case letters aren't supported, you must use lowercase letters for the repository owner even if the GitHub user or organization name contains uppercase letters.

When you route all package requests through GitHub Package Registry, you can use both scoped and unscoped packages from npmjs.com.

For more information, see "npm-scope" in the npm documentation.

Configuring a package scope using a local .npmrc

Using a .npmrc can help ensure that other developers who publish the package won't accidentally publish it to npmjs.org.

  1. In your project directory, create or edit your .npmrc file to contain the line below. Replace OWNER with the name of the user or organization account on GitHub that owns the repository where you will publish the package. This will route all package requests through GitHub Package Registry.

    registry=https://npm.pkg.github.com/OWNER
  2. Check the local .npmrc into your Git repository, in the same directory as your package.json file.

  3. Verify the name of your package in your project's package.json. The name field must contain the scope and the name of the package. For example, if your package is called "test", and you are publishing to the "My-org" GitHub organization, the name field in your package.json should be @my-org/test. Because upper case letters aren't supported, you must use lowercase letters for the repository owner even if the GitHub user or organization name contains uppercase letters.

  4. Verify the repository field in your project's package.json. The repository field must match the URL for your GitHub repository. For example, if your repository URL is github.com/my-org/test then the repository field should be git://github.com/my-org/test.git.

  5. Publish the package:

    $ npm publish
  6. You can access your packages from this URL by replacing OWNER with your GitHub user or organization name and REPOSITORY with your repository name:

    https://github.com/OWNER/REPOSITORY/packages

Configuring a package scope using publishConfig in package.json

You can set the registry that a package should be published to by using the publishConfig element in the package.json file. For more information, see "publishConfig" in the npm documentation.

  1. Edit the package.json file for your package and include a publishConfig entry.

    "publishConfig": {
        "registry":"https://npm.pkg.github.com/"
      },
  2. Verify the repository field in your project's package.json. The repository field must match the URL for your GitHub repository. For example, if your repository URL is github.com/my-org/test then the repository field should be git://github.com/my-org/test.git.

  3. Publish the package:

    $ npm publish
  4. You can access your packages from this URL by replacing OWNER with your GitHub user or organization name and REPOSITORY with your repository name:

    https://github.com/OWNER/REPOSITORY/packages

Publishing multiple packages to the same GitHub repository

When you publish a package, by default GitHub Package Registry uses the package name to determine the GitHub repository where it will be published. For example, a package named @my-org/test would be published to the my-org/test GitHub repository.

If you would like to publish multiple packages to the same repository, you can include the URL to the GitHub repository in the repository field of the package.json. GitHub will match the repository based on that field, instead of based on the package name.

"repository" : {
    "type" : "git",
    "url": "ssh://git@github.com/OWNER/REPOSITORY.git"
  },

For more information on creating your package, see "How to create Node.js Modules" in the npm documentation.

Receiving package registry events

You can receive webhook events when a package is published or updated. For more information, see "RegistryPackageEvent" in the GitHub Developer documentation.

Installing a package

Using packages from GitHub in your projects is similar to using packages from npmjs.com. Add your package dependencies to your package.json specifying the full package name. For packages from GitHub Package Registry, specify the full scoped package name, like @my-org/server. For packages from npmjs.com, specify the full name, like @babel/core or @lodash.

Because upper case letters aren't supported, you must use lowercase letters for the repository owner even if the GitHub user or organization name contains uppercase letters.

  1. Authenticate to GitHub Package Registry using either a .npmrc file or with npm login. For more information, see "Authenticating to GitHub Package Registry."

  2. We recommend creating a local .npmrc in the project that points to GitHub Package Registry. This will ensure other developers on your project who run npm install can access your organization's dependencies from GitHub Package Registry as well as any packages needed from npmjs.org. Add a line to .npmrc, replacing OWNER with the name of the user or organization account on GitHub that owns the repository where you will publish the package.

    registry=https://npm.pkg.github.com/OWNER
  3. Check the local .npmrc file into your Git repository.

  4. Configure package.json to use the package. For example, this package.json uses the @octo-org/octo-app package as a dependency.

    {
      "name": "@my-org/server",
      "version": "1.0.0",
      "description": "Server app that uses the @octo-org/octo-app package",
      "main": "index.js",
      "author": "",
      "license": "MIT",
      "dependencies": {
        "@octo-org/octo-app": "1.0.0"
      }
    }

    Note: The summary for the package listing page comes directly from the description field in package.json.

  5. Install the package.

    $ npm install

For more information on using a package.json in your project, see "Working with package.json" in the npm documentation.

Installing packages from other organizations

By default, you can only use GitHub Package Registry packages from one organization. If you'd like to route package requests to multiple organizations and users, you can add additional lines to your .npmrc file, replacing OWNER with the name of the user or organization account.

registry=https://npm.pkg.github.com/OWNER
@OWNER:registry=https://npm.pkg.github.com
@OWNER:registry=https://npm.pkg.github.com

Deleting a package

To avoid breaking projects that may depend on your packages, GitHub Package Registry does not support deleting published versions of a package or an entire published package for public repositories. Under special circumstances, such as for legal reasons or to conform with GDPR standards, you can request deleting a package through GitHub Support. Contact GitHub Support using our contact form and the subject line "GitHub Package Registry."

You can delete private packages via GitHub's API. For more information, see "Access to package version deletion" in the GitHub Developer documentation.

Ask a human

Can't find what you're looking for?

Contact us