updates

April 29, 2026 · View on GitHub

updates is a CLI tool which checks for dependency updates. It is typically able to complete in less than a second.

Supported files

package.json, pnpm-workspace.yaml - npm dependencies
pyproject.toml - uv dependencies
go.mod, go.work - go dependencies
Cargo.toml - rust dependencies, including workspaces
.{github,gitea,forgejo}/workflows - actions and docker images
Dockerfile*, docker-*.{yml,yaml} - docker images

Usage

# check for updates
npx updates

# update package.json and install new dependencies
npx updates -u && npm i

Options

Option	Description
`-u, --update`	Update versions and write dependency file
`-f, --file <path,...>`	File or directory to use, defaults to current directory
`-M, --modes <mode,...>`	Which modes to enable. Either `npm`, `pypi`, `go`, `cargo`, `actions`, `docker`. Default: `npm,pypi,go,cargo,actions,docker`
`-i, --include <dep,...>`	Include only given dependencies
`-e, --exclude <dep,...>`	Exclude given dependencies
`-l, --pin <dep=range>`	Pin dependency to given semver range
`-C, --cooldown <duration>`	Minimum dependency age, e.g. `7` (days), `1w`, `2d`, `6h`
`-p, --prerelease [<dep,...>]`	Consider prerelease versions
`-R, --release [<dep,...>]`	Only use release versions, may downgrade
`-g, --greatest [<dep,...>]`	Prefer greatest over latest version
`-t, --types <type,...>`	Dependency types to update
`-P, --patch [<dep,...>]`	Consider only up to semver-patch
`-m, --minor [<dep,...>]`	Consider only up to semver-minor
`-d, --allow-downgrade [<dep,...>]`	Allow version downgrades when using latest version
`-S, --sockets <num>`	Maximum number of parallel HTTP sockets opened. Default: 96
`-T, --timeout <ms>`	Network request timeout in ms (go probes use half). Default: 5000
`-r, --registry <url>`	Override npm registry URL
`-I, --indirect`	Include indirect Go dependencies
`-E, --error-on-outdated`	Exit with code 2 when updates are available and 0 when not
`-U, --error-on-unchanged`	Exit with code 0 when updates are available and 2 when not
`-j, --json`	Output a JSON object
`-x, --no-cache`	Disable HTTP cache
`-n, --no-color`	Disable color output
`-v, --version`	Print the version
`-V, --verbose`	Print verbose output to stderr
`-h, --help`	Print the help

Options that take multiple arguments can take them either via comma-separated value or by specifying the option multiple times. If an option has a optional dep argument but none is given, the option will be applied to all dependencies instead. All dep options support glob matching via * or regex (on CLI, wrap the regex in slashes, e.g. '/^foo/').

Config File

The module can be configured with updates.config.{ts,js,mjs,mts} in your repo root.

import type {Config} from "updates";

export default {
  pin: {
    "typescript": "^6",
  },
} satisfies Config;

Config Options

include Array<string | RegExp>: Array of dependencies to include
exclude Array<string | RegExp>: Array of dependencies to exclude
types Array<string>: Array of dependency types to use
registry string: URL to npm registry
cooldown number | string: Minimum dependency age, e.g. 7 (days), "1w", "2d", "6h"
pin Record<string, string>: Pin dependencies to semver ranges
files Array<string>: File or directory paths to use
modes Array<string>: Which modes to enable
greatest boolean | Array<string | RegExp>: Prefer greatest over latest version
prerelease boolean | Array<string | RegExp>: Consider prerelease versions
release boolean | Array<string | RegExp>: Only use release versions
patch boolean | Array<string | RegExp>: Consider only up to semver-patch
minor boolean | Array<string | RegExp>: Consider only up to semver-minor
allowDowngrade boolean | Array<string | RegExp>: Allow version downgrades
inherit object: Opt-in to inheriting select fields from other tools' configs (see Renovate config)

CLI arguments have precedence over options in the config file. include, exclude, and pin options are merged.

Renovate config

If a Renovate config is found, ignoreDeps and simple packageRules are inherited as exclude/pin. minimumReleaseAge is not inherited as cooldown by default — opt in via:

export default {
  inherit: {
    renovate: {cooldown: true},
  },
} satisfies Config;

Values in updates.config override anything inherited.

API

updates can be used as a library:

import {updates} from "updates";

const output = await updates({
  files: ["package.json"],
  include: [/^react/],
  modes: ["npm"],
});
//=> {
//=>   "results": {
//=>     "npm": {
//=>       "dependencies": {
//=>         "react": {
//=>           "old": "18.0.0",
//=>           "new": "19.2.0",
//=>           "info": "https://github.com/facebook/react",
//=>           "age": "2 days"
//=>         }
//=>       }
//=>     }
//=>   }
//=> }

The updates() function accepts all config options.

Environment Variables

Variable	Description
`UPDATES_FORGE_TOKENS`	Comma-separated list of `host:token` pairs for authenticating against forge APIs (e.g. `github.com:ghp_xxx,gitea.example.com:tok_xxx`)
`UPDATES_GITHUB_API_TOKEN`	GitHub API token for authenticating forge API requests
`GITHUB_API_TOKEN`	Fallback GitHub API token
`GH_TOKEN`	Fallback GitHub API token
`GITHUB_TOKEN`	Fallback GitHub API token
`HOMEBREW_GITHUB_API_TOKEN`	Fallback GitHub API token
`GOPROXY`	Go module proxy URL. Default: `https://proxy.golang.org,direct`
`GONOPROXY`	Comma-separated list of Go module patterns to fetch directly, bypassing the proxy
`GOPRIVATE`	Fallback for `GONOPROXY` when not set

Token resolution order for forge APIs: UPDATES_FORGE_TOKENS (matched by hostname) > UPDATES_GITHUB_API_TOKEN > GITHUB_API_TOKEN > GH_TOKEN > GITHUB_TOKEN > HOMEBREW_GITHUB_API_TOKEN.