⚡ A fast, tiny package manager for the npm registry, written in TypeScript.

• 🟦 Pure JS: built with TypeScript and Node.js builtins.
• 🪶 Small: about 251 KB on disk (84 KB packed), small enough to bundle into your own tools.
• 🚀 Fast: install speed on par with package managers written in Rust.
• 🧩 Programmable: every command is also a JavaScript function you can import.
• 🎯 Simple: no new config files or conventions. Your existing .npmrc just works.
• 🔒 Secure: defaults to a 1-day minimum release age and skips dependency lifecycle scripts.
• 📦 Lockfile compatibility: supports existing package-lock.json, pnpm-lock.yaml and bun.lock out of the box.

🤔 Why another package manager?

There are already several popular package managers:

• npm ships with Node.js, but it is simply slow.
• pnpm is fast and well designed, but it keeps growing in size, features and customization settings.
• Yarn (berry) has become complex, with its own concepts and unusual requirements.
• Bun, Deno and Nub are fast, but they fit best when you also use them as runtime and not Node.js.

• 🟢 Node.js is capable. It already has worker threads, zlib, fetch and every other needed feature.
• 🦀 Native package managers are much larger to download and store on disk, for every version. In CI, just fetching the binary, even from a cache, can cost more time than it could save! Most of the bytes in these binaries are already native features that Node.js already has. In our benchmarks, aube takes 152 MB and pnpm 12 takes 57 MB on disk; upm ~251 KB.
• 🔌 Programmatic API. The only possible way to install dependencies is spawing command in a separate process. None of the current package managers are small enough to bundle and embed into another library.

Get started

Install upm globally. The scripts check for Node.js 22.3+, then install upm with npm.

# macOS / Linux
curl -fsSL https://upm.sh/install.sh | sh
Windows (PowerShell)
irm https://upm.sh/install.ps1 | iex
npm
npm i -g upm --min-release-age 0

Then install your project's dependencies:

upm i

[!IMPORTANT]

Prerelease: upm is not stable yet see current limits.

Quick reference

upm install                          # install the project's dependencies (also upm alone)
upm add vue@^3 nanoid                 # save to package.json, then install
upm add --dev vitest                  # save as a dev dependency
upm add --optional fsevents           # save as an optional dependency
upm add --exact nanoid                # save the selected version without a caret
upm remove nanoid                     # remove from package.json, then install
upm add shared -w app                 # add a dependency to workspace app
upm run                              # list project scripts
upm run build                        # run the project's build script
upm run --workspaces build           # build workspaces in dependency order
upx cowsay hello                     # run a package's command, installing it if needed
upm dedupe                           # reduce duplicate versions already locked
upm install --production             # skip packages used only by dev dependencies
upm install --frozen-lockfile        # CI: fail if the lockfile is missing or stale
upm install --verify                 # check sizes and links, not file hashes
upm install --offline                # no network: install from upm.lock and the store
upm lock                             # write upm.lock without installing packages
upm resolve vue@^3                   # show which registry version matches
upm fetch nanoid                     # cache this package, without its dependencies
upm fetch --lock                     # cache this platform's locked packages
upm prune                            # clean up old entries and unreferenced files

Commit upm.lock with your package.json. When switching to upm, delete the old node_modules first. Otherwise, your code may still import old packages.

Use --dir to choose a project directory. Otherwise, install commands look for the nearest package.json above the current directory, or the workspace root that lists it. --dir uses the directory you give it; for a workspace tree, point it at the root and use -w where supported.

Most commands support --json for machine-readable results. Progress and warnings go to stderr. upm lock --json prints the lockfile without writing it. See upm --help for all options, including experimental worker settings.

Add and remove packages

upm add vue@^3 nanoid
upm add --dev vitest                  # -D also works
upm add --optional fsevents           # -O also works
upm add --exact nanoid                # -E also works
upm add sw@npm:string-width@^4        # install string-width under the name sw
upm remove nanoid

upm alone and upm i are short for upm install, and upm install ... is another way to write upm add ....

• By default, add saves to dependencies. Use --dev or --optional for the

• An explicit version or range is saved as written: vue@^3 saves ^3.
• A bare name, *, or a tag such as latest saves a caret range of the selected

• remove takes a name out of all three dependency groups. It fails if the name

• Unrelated dependencies keep their locked versions after an add or remove.

Install from a tarball

upm add ./vendor/lib-1.0.0.tgz        # saves "lib": "file:vendor/lib-1.0.0.tgz"
upm add https://example.com/lib-1.0.0.tgz
upm add other@https://example.com/lib-1.0.0.tgz

A dependency can be an http:// or https:// URL of a tarball, or a path to a .tgz, .tar.gz or .tar file, written file:vendor/lib.tgz, ./vendor/lib.tgz or ../lib.tgz. Given without a name, add uses the name in the tarball's package.json. In package.json, a path is relative to that file, so only the root and workspaces can use one; add reads a path from the current directory and saves it that way. Absolute paths are refused because they would not work on another machine. A directory is not supported: make it a workspace or pack it.

A tarball is read when it is first locked. upm.lock keys it by its URL or root-relative path and records the integrity of its bytes. Its own dependencies come from the registry.

A local tarball is part of the project, like package.json: when you replace it (say, after npm pack again), the next install reads it again and locks the new bytes, leaving the rest of the tree as it was. Each install checks the file's size and times first and hashes it only when they change. --frozen-lockfile fails instead, as the lockfile is out of date. A URL is not read again: the lockfile pins its bytes, and an install that has to fetch it fails with EINTEGRITY if the server now sends others. To take a new version, point the dependency at a new URL, or remove it and add it again. Credentials in .npmrc are sent to a URL on the same host, as for a registry.

Performance

upm aims to make cached and repeat installs cheap by reusing files and saved install state. Actual times depend on the package tree, network, filesystem, and available CPU.

Other charts: Peak memory (cold, warm, repeat). CPU time (cold, warm, repeat).

The benchmark guide explains how to compare cold, warm, and repeat installs with other package managers. It uses private caches and disables lifecycle scripts for a fairer comparison.

JavaScript API

The commands are also available as functions from upm:

import { add, install, lock, resolve, run } from "upm";
// Install from the lockfile, failing if it is out of date
const result = await install({
  dir: "./my-project",
  frozen: true,
  log: (message, level) => console.error([${level}] ${message}),
}); // { packages: 120, workspaces: 0, upToDate: false, stats, ... }
// Add a dependency to package.json and install it
await add(["vue@^3"], {
  dir: "./my-project",
  group: "dependencies",
}); // { added: [{ name: "vue", range: "^3", group: "dependencies" }], ... }
// Resolve a spec to a version without installing
const [vue] = await resolve(["vue@^3"]); // { name: "vue", version: "3.5.13", dist, ... }
// Build the lockfile in memory without writing it
const lockfile = await lock({ dir: "./my-project", write: false }); // { root, packages, ... }
// Run the build script in every workspace
const { code, results } = await run("build", {
  dir: "./my-project",
  workspaces: "all",
  install: true, // install the tree first, as upm run does
}); // { code: 0, results: [{ name: "app", path, file, code: 0 }] }
// Other exports
import {
  dedupe, // re-resolve, preferring locked versions, then install
  exec, // run a package's bin, installing it if needed
  fetchLockfile, // fill the store from the lockfile, no linking
  fetchPackages, // resolve specs and fill the store, no linking
  listScripts, // list package.json scripts
  prune, // drop unused store and project entries
  remove, // remove dependencies, then install
} from "upm";
// Experimental resolver API (works in browser too)
import {
  createRegistry, // registry client that fetches packuments
  formatLockfile, // lockfile object to text
  fromLockfile, // lockfile object to resolution
  parseLockfile, // lockfile text to object
  parseSpec, // parse a spec such as "vue@^3"
  resolveTree, // resolve a dependency tree
  toLockfile, // resolution to lockfile object
} from "upm/resolver";

Functions return data and do not print their own messages. Use log for progress, warnings, and debug messages, and onProgress (install, add, remove, dedupe, lock) for counts to draw a progress bar from. run and exec still share the child's terminal input and output.

Errors have a code you can handle. The exported ErrorCode type lists common codes; filesystem and worker errors may have others. Options under experimental and the diagnostic InstallStats fields may change in any release. See src/api.ts for options and result types.

The main upm entry needs Node.js. Its worker threads start from code inside it, not from separate files, so it can be bundled into your app; when no thread can start, it works on one thread and warns through log. The experimental upm/resolver entry provides the registry client, dependency resolver, and in-memory lockfile tools without requiring Node. It does not install files or read .npmrc for you. See src/resolver.ts for its exports.

Store backend

storeBackend puts shared storage behind the store: a team cache, a key-value database, the browser's OPFS. upm asks it for a package before downloading one, and hands it each package it downloads before the command returns. The store is still a real directory that projects link from.

A backend holds bytes by key; upm decides the keys and what they hold:

import { install } from "upm";
const data = new Map();
await install({
  storeBackend: {
    get: async (key) => data.get(key),
    set: async (key, value) => void data.set(key, value),
  },
});

Keys are /-separated and safe as file names, and a key's value never changes. An optional getMany(keys) reads several in one call. Without set, the backend is only read. Packages downloaded with credentials are not handed to it unless it says it is private.

A backend must be trusted as the store is: it decides what a package holds. Its files are checked against their hashes unless it says it is trusted, and its paths must stay inside the package. A failure or a call quiet for 30 s counts as a miss, and upm downloads instead. See StoreBackend in src/store-backend.ts.

Lockfiles and CI

upm install --frozen-lockfile
upm install --production --frozen-lockfile
upm ci --omit=dev                    # the same, in npm's words

--frozen-lockfile fails if upm.lock is missing, invalid, or out of date with the project. It does not select versions or rewrite the lockfile. Missing cached packages still need to be downloaded, so this is not an offline mode.

An install that links node_modules from upm.lock leaves a copy of it in node_modules/.upm.lock, as npm and pnpm keep one. When upm.lock is missing and that copy still matches package.json, upm install (and dedupe) writes it back and goes on from it: a tree that is already installed is then up to date without the store or the network. If package.json has changed, the copy is ignored and the install resolves as if there were no node_modules. upm lock and --frozen-lockfile never read the copy.

Registry documents that upm reads while resolving are kept in the store's metadata directory, under paths named after the registry and package (metadata/registry.npmjs.org/@scope/name/), so deleting a directory forgets those documents. A full document is kept cut down to the fields upm reads, and each notes where its versions are, so a pick parses only the versions it looks at. A kept document is used without a request within the max-age the registry sent (five minutes on npmjs), and, while min-release-age is on, for as long as it was fetched after the cutoff: any version it lacks is too new to pick. After that, upm asks with its ETag and reuses it on a 304. A tag written out, such as upm exec foo@latest, is always asked about. When a document used without asking cannot satisfy a range or pin, upm asks the registry once.

--offline never uses the network. An install from a current lockfile works when the store already holds its packages, which a past install on the same machine leaves there. A new version is picked from kept documents, however old. Anything else that needs the registry or a download fails at once with EOFFLINE, including a missing optional package.

--prefer-offline also picks from kept documents however old, and asks the registry only for a name with no kept document, or one whose kept document cannot satisfy the range. Tags such as latest may then be out of date.

--production skips packages used only by devDependencies. It uses the same lockfile as a development install; it does not create a smaller lockfile.

The lockfile keeps optional builds for all platforms. At install time, upm uses the current OS, CPU, and libc to select the right builds. For example, on Linux it distinguishes glibc from musl builds of native packages. The lockfile is designed to be shared across machines, but that does not mean the installer is fully tested on every platform. Incomplete registry metadata can also hide some libc-only restrictions.

You can prepare the cache separately:

upm lock
upm fetch --lock
Or fetch only production packages:
upm fetch --lock --production

fetch --lock reads an existing lockfile; it does not refresh it or check it against package.json. It fetches packages for the current platform only.

Other package managers' lockfiles

If there is no upm.lock, upm can install the versions listed in package-lock.json, pnpm-lock.yaml or bun.lock. It leaves that file unchanged and does not create an upm.lock.

When using another manager's lockfile, upm does not support add, remove or dedupe. Installation also fails if the lockfile no longer matches package.json. Use the original package manager to update the lockfile, or delete it to let upm create its own.

upm cannot use these lockfiles if they include workspaces, patches, or git or file dependencies. bun.lock does not say which packages need glibc or musl, so upm installs both builds on Linux.

Run scripts

upm run                   # list scripts
upm run build
upm test --watch           # short for upm run test --watch
upm vitest --run           # no vitest script: runs node_modules/.bin/vitest
upm run test -- --watch    # the first -- is optional
upm run --dir ./app build
upm run --if-present lint  # no lint script is not an error

Before a script runs, upm installs the project it belongs to, workspace root and all, so dependencies are current. When nothing changed this is a quick check, and a tree installed with --production stays that way. A project that declares no dependencies and was never installed is left alone.

Scripts run in a shell from the selected package directory. Local node_modules/.bin directories are added to PATH, so scripts can use installed command-line tools. Script output goes straight to your terminal.

Put upm's own options before the script name. Everything after the name is passed to the script. upm without run falls back to an installed bin of that name when there is no such script; it never installs one. Only the named script runs: upm does not run prebuild, postbuild, or other pre/post hooks automatically.

Without workspace options, run uses the package.json in the current directory, or in --dir. Unlike install, it does not search parent directories.

By design, upm does not run dependency lifecycle scripts during installation. Packages that rely on install or postinstall scripts to build or download files may need extra setup.

Run package commands

upx vitest --watch                    # the project's vitest when installed
upx [email protected] hello                # an exact version, installed once
upx -p typescript@5 tsc --version     # install packages, then run any command
upx -p eslint -p prettier -c 'eslint . && prettier --check .'
upm exec eslint .                     # upx is short for upm exec

upx runs a package's command from the current directory, or --dir. As with npm, a command in the nearest package.json's own bin comes first. Next, a name without a version uses a command or package already in a node_modules above that directory, and a version or range uses an installed package that matches it. A tag such as @latest always asks the registry.

Otherwise upm installs the package into its own project, linked from the shared store: under node_modules/.upm/.exec of the project root, so it is removed with that node_modules and can import what the project installed, or under ~/.upm/exec when the root has no node_modules. It runs the package's only command (or one file with several names), or the one named after the package. Use -p when a package has several commands or when the command has another name. A tag or range asks the registry for the newest match each time; each set of versions is installed once.

-c '' runs a whole line in the shell instead, so &&, pipes and variables work. The -p packages are installed first and on PATH; without -p, only the local node_modules/.bin directories are, and nothing is installed.

Put upm's own options before the command; everything after it is passed to the command. The current project's .npmrc chooses the registry and credentials. There is no prompt before installing (-y is accepted and does nothing), and packages run no install scripts.

npm commands

upm login
upm version minor
upm publish --tag next                # upm exec npm publish --tag next

npm's commands for the registry, your account and package.json run npm itself, exactly as upm exec npm : the project's own npm when installed, otherwise the latest from the registry. They are access, config, create, deprecate, dist-tag, info, init, login, logout, org, owner, pack, ping, pkg, profile, publish, search, show, stage, team, token, trust, undeprecate, unpublish, version, view and whoami. Only --dir goes before the command; everything after it is npm's. Use upm run for a script with one of these names. They run with npm's workspaces-update off, so version and init in a workspace never let npm install the tree.

npm reads the same .npmrc files, so upm login stores a token upm uses too. Commands that read or change the installed tree, such as ls, outdated, audit or update, are not passed on: npm does not understand upm's node_modules layout or upm.lock.

npm's command lines

Most npm install and run lines work as they are:

• upm ci is upm install --frozen-lockfile. uninstall, rm, r and un are

• --save-dev, --save-optional and --save-exact are -D, -O and -E.

{
  "private": true,
  "workspaces": ["packages/*", "!packages/legacy"]
}

{
  "name": "app",
  "dependencies": {
    "shared": "workspace:*"
  }
}

upm add shared -w app                     # save a caret range of shared's local version
upm add 'shared@workspace:*' -w app       # require the local workspace
upm add --dev vitest -w app
upm remove vitest -w app
upm run -w app build
upm run --workspaces --if-present build
upm run --workspaces --include-workspace-root build

registry=https://npm.example.com/
@acme:registry=https://npm.example.com/acme/
//npm.example.com/:_authToken=${NPM_TOKEN}
save-exact=true

min-release-age=7
min-release-age-exclude[]=@acme/*
min-release-age-exclude[]=my-internal-pkg

upm install --verify

upm prune