Skip to content


Repository files navigation


npm NPM npm

The command-line tool to maintain the Unity manifest file for 3rd-party upm registries, offering a similar but lighter experience like npm or yarn for Node.js.

The tool is designed to work with the OpenUPM registry, but can also work with any upm registries, including the official Unity registry.

How it works

The command-line tool installs the 3rd-party registry as a scoped registry and maintains the Packages/manifest.json file when adding/removing packages. If the manifest file is modified, the Unity Package Manager will detect the changes and try to resolve the package dependencies.

Notice: the command-line tool does not directly install/uninstall package tarballs, at least for now.


  • Requires nodejs 18 or above.

  • Install via npm:

    npm install -g openupm-cli
  • Or install via yarn:

    yarn global add openupm-cli

Windows platform troubleshooting

If npm is not available in your CMD/PowerShell/Git-Bash, please configure your environment variables.

# for npm
c:\Program Files\nodejs

# for npm global bin

Cannot find module 'node:net'

  throw err;

Error: Cannot find module 'node:net'

Please install Node.js 18 or above.


Add packages

openupm add <pkg> [otherPkgs..]
openupm add <pkg>@<version>
openupm add <pkg>
openupm add <pkg>@
openupm add <pkg>@file:...

The add command adds the package to the manifest.json and configures the scope registry by adding scopes for the package and its dependencies that available on the registry.

The add command doesn't verify package or resolve dependencies for Git, HTTPS, and file protocol. See for more examples of the version string.

The add command fails if the package is not qualified:

  • the package has a missing dependency
  • the package requires a non-existed dependency version
  • the package requires a higher editor version

You shall either resolve these issues manually or add the option -f to continue.

You can also add testables when importing:

openupm --test <pkg>

Remove packages

openupm remove <pkg> [otherPkgs...]

Search packages

openupm search <keyword>

If the registry doesn't support the new search endpoint, it will fall back to the old /-/all endpoint. If no package was found, it will search the Unity official registry instead.

Because the upstream Unity registry doesn't support the search endpoint as of December 2019, the search command will only query the current registry.

View package information

openupm view <pkg>

View package dependencies

open deps <pkg>

Using option --deep to view dependencies recursively

open deps <pkg> --deep

Authenticate with a scoped registry

Starting from Unity 2019.3.4f1, you can configure the.upmconfig.toml file to authenticate with a scoped registry. The openupm login command helps you authenticate with a npm server and store the info to the UPM config file.

There are two ways to authenticate with a npm server:

  • using token (recommended): a server-generated string for the grant of access and publishing rights.
  • using basic authentication: the username:password pair (base64 encoded) is stored to authenticate with the server on each request.

After login, all openupm-cli commands will use .upmconfig.toml configuration to authenticate with your private scoped registry.

Using token

openupm login -u <username> -e <email> -r <registry> -p <password>

openupm login -u user1 -e -r

If you don't provide a username, email, or password, it will prompt you to input the value. If your npm server doesn't require an email field, you can provide a dummy one like Notice that requesting a new token is not meant to invalidate old ones for most NPM servers.

For the npm server to allow user creation via CLI, providing a new username will create a new user with the information you just provided.

The token is also stored in the .npmrc file for convenience.

Using basic authentication

Adding --basic-auth option to use basic authentication.

openupm login -u <username> -e <email> -r <registry> -p <password> --basic-auth

openupm login -u user1 -e -r --basic-auth

Notice that your username and password is not verified during the login command, but simply stored in the .upmconfig.toml file. Because verify the password against your npm server will generate a token, which is not what you want here. Please type your password carefully.

Unlike using the token, .npmrc lacks syntax to support multiple registries for basic authentication. Hence, the .npmrc is not updated for the basic authentication.

Always auth

Adding --always-auth option if tarball files are hosted on a different domain other than the registry domain.

openupm login -u <username> -e <email> -r <registry> -p <password> --always-auth

openupm login -u user1 -e -r --always-auth

Windows Subsystem for Linux (WSL)

By default, the command treats the Windows Subsystem for Linux (WSL) as a Linux system. But if you want to authenticate for the Windows (probably where your Unity installed on), add --wsl option.

Known issue: run with --wsl option may clear the terminal screen during the process.

Authenticate for the Windows system user

Make sure you have the right permission, then add --system-user option to authenticate for the Windows system user.


You can verify the authentication in .upmconfig.toml file:

  • Windows: %USERPROFILE%/.upmconfig.toml
  • Windows (System user) : %ALLUSERSPROFILE%Unity/config/ServiceAccounts/.upmconfig.toml
  • MacOS and Linux: ~/.upmconfig.toml

For token, it will look like:

email = "email address"
alwaysAuth = false
token = "token string"

For basic authentication, it will look like:

email = "email address"
alwaysAuth = true
_auth = "base64 string"

Notice that the registry address should match exactly with your manifest.json. The last slash is always trimmed. i.e. instead of

Learn more about authentication at

Command options

The cli assumes the current working directory (CWD) is the root of a Unity project (the parent of the Assets folder). However, you can specify the CWD.

openupm --chdir <unity-project-path>

Specify another 3rd-party registry (defaults to the openupm registry)

openupm --registry <registry-url>

openupm --registry

Show verbose logging

openupm --verbose ...

Work with Unity official (upstream) registry

Most commands can fall back to Unity upstream registry if necessary, to make it easier to mix the official registry with a 3rd-party registry. i.e.

$ openupm add com.unity.addressables com.littlebigfun.addressable-importer
added: com.unity.addressables@1.4.0                # from unity registry
added: com.littlebigfun.addressable-importer@0.4.1 # from openupm registry

Turn off Unity official (upstream) registry

openupm --no-upstream ...

Work with proxy

OpenUPM-CLI supports HTTP, HTTPS, or SOCKS proxy specified by the http_proxy environment variable.

http_proxy="" openupm ...

You may need to set both http_proxy and https_proxy environment variables at the system-level to enable Unity work with a proxy.


Favo Yang
Favo Yang

💻 🚧
Ramon Brullo
Ramon Brullo

💻 🚧
Koji Hasegawa
Koji Hasegawa

💻 🐛

Masahiro Yamaguchi
Masahiro Yamaguchi

Max Himmel
Max Himmel

Wilfredo Velázquez-Rodríguez
Wilfredo Velázquez-Rodríguez

Christopher Arendt
Christopher Arendt

Felix Winterhalter
Felix Winterhalter

Antoine Lelievre
Antoine Lelievre

Tyler Temp
Tyler Temp