upd

Update dependencies across a polyglot repository—locally, safely, and in one command.

Python · Node.js · Rust · Go · Ruby · .NET · Gradle · Docker · Terraform · Nix flakes · GitHub Actions · pre-commit · Mise

upd gives you one reviewable update plan across mixed stacks. It preserves hand-written constraints, comments, and formatting; previews every proposed change before it writes; and runs without a hosted service or repository onboarding.

Try it now

From any directory inside a Git repository:

uvx upd

That first run is a dry run: it reports what would change and leaves every file untouched. No repository onboarding or hosted account is required. Review the plan, then apply it with uvx upd --apply.

_{One preview across four file types. Nothing changes until you pass --apply.}

Install another way · See every supported file · Compare dependency tools

Why upd

• One command for a mixed stack. Check application dependencies, tool versions, container images, GitHub Actions, pre-commit hooks, and Terraform modules in the same run instead of assembling a different updater for each file type.
• Safe on the first run. Dry-run is the default, constraints and formatting are preserved, and major updates are called out before you decide what to apply.
• Local first, automation ready. Start with an interactive terminal review, then use the same CLI, configuration, stable exit codes, JSON/SARIF output, and rolling PR or MR workflows in CI.

upd is a local checker and editor, not a package manager or a hosted update bot. It can delegate lockfile refreshes to the package managers already in your project and can run inside your own GitHub or GitLab automation. A refresh writes the lockfile without installing packages or syncing an environment; the exact command per ecosystem, and the one old bun release that is the exception, are listed under Commands run by --lock. See the decision guide and dated benchmarks for an exact comparison with adjacent tools.

For uv projects, upd update --apply --lock runs exactly uv lock after changing a manifest with an existing lockfile (at the workspace root when applicable). It passes no flags and never runs uv sync; synchronize your Python environment separately. Without --lock, a normal update refreshes neither the lockfile nor the environment. upd audit --fix-audit --apply refreshes applicable lockfiles by default; --no-lock opts out.

Where upd fits

Choose by the job rather than treating every dependency tool as interchangeable:

Dated performance evidence

On the committed 18-reference fixture, the verified 2026-08-28 run recorded:

Lower is better. These are five-run live-network observations, not universal speed claims. Every timed update was first verified to change all intended references and leave a parseable result. See the full matrix, methodology, variance, commands, and raw JSON.

Features

• Multi-ecosystem: Python, Node.js, Rust, Go, Ruby, .NET, Docker, Terraform, Nix flakes, GitHub Actions, pre-commit, Mise/asdf
• Dry-run by default: nothing is written without --apply
• Fast: parallel registry requests, with a 24-hour version cache
• Constraint-aware: respects >=2.0,<3 (Python), ~> 7.1 (Ruby), and ^2.0.0 / ~2.0.0 (npm, Cargo)
• Format-preserving: keeps formatting, comments, and structure
• Update filters: --only-bump, --max-bump, --package (exact names or quoted globs such as 'shiny*'), --lang, --exclude-lang, or approve one by one with -i
• Major warnings: breaking changes are flagged with (MAJOR)
• Pre-release aware: updates pre-releases to newer pre-releases
• Cooldown: hold back releases younger than N days, against supply-chain attacks
• Security auditing: OSV vulnerability scanning with auto-fix and SARIF output
• Check mode: exit 1 if updates are available (for CI and pre-commit)
• Gitignore-aware: honors .gitignore and prunes hidden directories, without missing the dotfiles it updates
• Private registries: authentication for PyPI, npm, Cargo, Go, and GitHub
• Config file: include or exclude paths, ignore packages, and pin versions via .updrc.toml

Installation

From crates.io

cargo install upd

# or with cargo-binstall (faster, pre-built binary)
cargo binstall upd

From PyPI

pip install upd
# or with uv
uv pip install upd

If you installed an earlier release under the old distribution name, migrate once with pip uninstall upd-cli && pip install upd. The upd-cli command remains available as a compatibility alias.

From source

git clone https://github.com/rvben/upd
cd upd
cargo install --path .

Usage

# Preview changes without modifying files (default when no --apply)
upd

# Apply updates to files
upd --apply

# Limit to specific files or directories
upd --apply requirements.txt pyproject.toml

# Approve updates one by one
upd -i

# Only the packages you name
upd -p requests,flask

# Select a package family (quote globs so your shell passes them to upd)
upd --package 'shiny*'

# Cap the bump level (allow patch + minor, skip major). Updates above the
# ceiling are reported as held back, never as up to date, and do not
# change the exit code.
upd --max-bump minor

# Restrict to exactly one level (repeatable, comma-separated)
upd --only-bump major

# Write nothing but registry versions at that level: pins, flake revisions
# and other level-less writes are reported as held instead of written
upd --only-bump major --strict-bump

# One ecosystem at a time: python, node, rust, go, ruby, dot-net,
# docker, terraform, nix, actions, pre-commit, mise, annotated
upd --lang python

# Both pre-commit YAML and prek.toml, including supported hook dependencies
upd --lang prek

# Exit 1 if anything is outdated (for CI and pre-commit)
upd --check

# Also reject unsafe or unverifiable dependencies blocked by safety checks
upd --check --fail-on-blocked

# Regenerate lockfiles after writing; a failed refresh rolls its directory back
upd --apply --lock

# Print the effective configuration and exit
upd --show-config

--fail-on-blocked is supported only by upd update or the default upd invocation. --check --fail-on-blocked exits 1 for safety refusals and 2 for failed registry requests. Unsupported Docker digest pins and bare pre-commit commit pins remain not-examined and do not fail this check. Pre-commit pins with a # frozen: <tag> comment are verified and updated together with that comment; a mismatch fails the strict check. The reusable workflow's fail-on-blocked input additionally covers unfixable or skipped version floors and blocked security relocks; see GitHub Actions.

upd --help lists every flag; Stability documents the ones that are contractual, and upd schema emits the whole interface as JSON.

--package accepts exact names and case-sensitive globs using *, ?, and character classes such as [ab]. Wildcards can cross namespace separators, so patterns such as '@scope/*' and 'github.com/org/*' work as expected. Quote globs on the command line to prevent shell expansion. A glob that matches no package produces a warning without changing the exit code; use repeated or comma-separated values instead of brace alternation.

Dry-run by default: upd without --apply only previews changes. Pass --apply to write updates. --check, --dry-run, and --interactive do not require --apply.

VCS-root scoping: When no path argument is given, upd scans from the nearest .git ancestor directory rather than the current working directory. This prevents accidental rewrites when CWD is a subdirectory inside a repository.

Commands

upd --version      # Print version
upd self-update    # Check for upd updates
upd clean-cache    # Clear the version cache
upd lock-refresh   # Refresh uv, npm, and Cargo locks within manifest constraints
upd align          # Align versions across files (--check exits 1 on misalignment)
upd audit          # Scan for known vulnerabilities (exit 6 if found)
upd schema         # Machine-readable interface description

For repositories replacing dependency bots, upd also provides separate reusable GitHub workflows for policy-constrained freshness updates and validated security-remediation pull requests. See GitHub dependency pull requests.

Example Output

.pre-commit-config.yaml:37: Would update pre-commit/pre-commit-hooks v4.6.0 → v6.0.0 (MAJOR)
.github/workflows/ci.yml:16: Would update actions/checkout v4 → v6 (MAJOR)
.github/workflows/ci.yml:18: Would update jdx/mise-action v2 → v4 (MAJOR)
.mise.toml:8: Would update rust 1.91.1 → 1.94.0
Cargo.toml:33: Would update clap 4.5.53 → 4.6.0
Cargo.toml:36: Would update tokio 1.48.0 → 1.50.0

Would update 6 package(s) (2 major, 3 minor, 1 patch) in 4 file(s), 8 up to date

Output includes clickable file:line: locations (recognized by VS Code, iTerm2, and modern terminals).

Version Constraints

upd respects version constraints in your dependency files:

An update moves the lower bound and leaves every other clause where the author wrote it, so >=1.0, <2.0 becomes >=1.5.0, <2.0. A constraint is an unordered set of clauses, so the lower bound is found wherever it sits (<2.0, >=1.0 answers alike), and an upper bound is honored when picking the new version: the release chosen is the newest one the constraint already admits.

npm ranges keep the shape they were written in. A comparator range (">=1.0.0 <2.0.0") and a hyphen range ("4.17.0 - 4.18.0") each keep their ceiling. A wildcard or partial range takes its ceiling from its own floor, like a caret, so it follows the newest release and the whole shape moves with it: "4.3.x" becomes "4.4.x" and "^1.2" becomes "^3.1", never a fully written version. npm lets a comparator stand apart from the version it applies to, and that spacing is part of the shape: ">= 1.2.7 < 1.3.0" is read as the range it is and comes back spaced the same way. npm's tilde has two spellings and "~>1.2.3" means what "~1.2.3" does, ceiling included; each comes back spelled the way it was written.

An npm spec that names no published version is left alone and reported nowhere: "*", a dist-tag ("latest", "next", "beta"), and the workspace:, file:, link:, npm:, git+ssh: and github:owner/repo forms all resolve somewhere other than a release on the registry, so there is no version to compare and nothing an update could move.

Python bump labels and --only-bump / --max-bump follow the changed release component: 0.0.77 → 0.0.78 is patch, and 0.77 → 0.78 is minor. Other ecosystems retain their existing pre-1.0 compatibility classification. Python update reports include each declaration's section and full constraint.

Specifier shape changes are opt-in. A [normalize.pyproject] table in .updrc.toml can independently make project dependencies, optional dependencies, or standardized dependency groups use ==, >=, or <=; projects without that table retain the shape-preserving behavior above. See the configuration guide.

Bounds that are not floors

Only an inclusive lower bound names the version a project is on, so only that bound is raised. >1.2.3 names the one version its author refuses, <3 and <=3 are ceilings, != 1.5 is an exclusion, and an OR range ("^1 || ^2") has no single branch to edit. None of them is a floor, so none of them is moved. They are checked against the registry and reported anyway:

The last row is the point of the other two: a dependency nothing looked at must not be counted as up to date, and a constraint that has quietly frozen a dependency should say so rather than pass under a green tick.

A PEP 440 prefix match reads the same way for the same reason. ==6.* and ==6.0.* name a series rather than a release, so there is no version in them to raise and nothing an update may write over them; they are checked and reported by the table above. pyyaml==6.* with 6.0.3 published is up to date, and rich==13.7.* with 15.0.0 published is a warning. [pin] and upd align answer the same way: neither writes a release into a specifier that has nowhere to hold one, and the pin reports an error rather than a rewrite.

Annotated Version Pins

Files without a dependency-manifest format can carry an inline annotation or one immediately above its value:

shinyhub_version: "0.11.16"  # upd: pypi shinyhub

Directory walks scan annotations in otherwise-unrecognized Makefile, makefile, GNUmakefile, justfile, Justfile, *.mk, *.sh, *.bash, *.yml, and *.yaml files. Any file passed explicitly is scanned as annotated. To add other files to normal repository discovery, use repository-relative globs in .updrc.toml:

include = ["deploy/*.env", "config/version.conf"]
exclude = ["**/archive/**"] # exclude wins over include

An include never changes a recognized manifest's parser: for example, a matching main.tf remains Terraform. Use --verbose to diagnose an upd: marker in an otherwise undiscovered UTF-8 text file up to 1 MiB.

Dockerfiles also scan annotated ARG and ENV versions alongside FROM updates:

# upd: pypi uv
ARG UV_VERSION=0.9.30

Use upd --apply to update both image tags and annotated versions. --lang annotated selects annotations only; --lang python selects PyPI annotations, and --lang docker selects image tags only. Place the comment immediately above a single-line ARG or ENV assignment. Docker treats inline # text as instruction arguments, so inline annotations are refused. Renovate comments such as # renovate: datasource=pypi depName=uv work too.

Downloaded GitHub release binaries can keep their version and SHA-256 together in any file scanned for annotations:

MISE_VERSION=2025.12.9 # upd: github-releases jdx/mise
MISE_CHECKSUM=afe7e9f2ea8e1704e9cc41e4b020798b8c60e5924ab4a313ccbf201a062f54d0 # upd: checksum MISE_VERSION asset=mise-v{version}-linux-x64.tar.gz

This works in Makefiles, shell scripts, YAML, GitHub workflows, and other explicitly selected text files. Add id=<name> to the version annotation when the version has no simple assignment key or the file repeats that key. The checksum references that ID. Comments may also immediately precede the value line; Dockerfiles require that form:

# upd: github-releases jdx/mise
ARG MISE_VERSION=2025.12.9

# upd: checksum MISE_VERSION asset=mise-v{version}-linux-x64.tar.gz
ARG MISE_CHECKSUM=afe7e9f2ea8e1704e9cc41e4b020798b8c60e5924ab4a313ccbf201a062f54d0

upd resolves the exact release asset's GitHub SHA-256 digest before updating both assignments. Add checksums=SHASUMS256.txt to explicitly use a release checksum manifest instead. If any linked checksum cannot be resolved, the entire version/checksum group stays unchanged. See linked release checksums for multiple architectures, templates, and diagnostics.

Check annotation syntax and checksum links without accessing any registry:

upd annotations validate Dockerfile versions.sh

upd annotations init <release-asset-url> --checksum <published-sha256> prints a linked snippet. Choose --syntax docker, shell, toml, yaml, or javascript; use --output text for plain text when piping it. Replace --checksum with --resolve-checksum to fetch the published digest online, optionally selecting a manifest with --checksums. Use --asset-template to override filename inference; it must expand exactly to the URL asset. Neither command writes files. See annotation tools for examples.

A GitHub Actions workflow keeps its Actions updater and is scanned for annotations as well, so a tool version passed to an action through a with: input can be updated beside the uses: refs around it. See GitHub Actions.

Version Precision

By default, upd preserves version precision from the original file:

# Original file has 2-component versions
flask>=2.0        →  flask>=3.1        (not 3.1.5)
django>=4         →  django>=6         (not 6.0.0)

# Original file has 3-component versions
requests>=2.0.0   →  requests>=2.32.5

# GitHub Actions major-only tags
actions/checkout@v3  →  actions/checkout@v4  (not @v4.2.0)

Use --full-precision to always output full semver versions:

upd --full-precision
flask>=2.0        →  flask>=3.1.5
django>=4         →  django>=6.0.0
requests>=2.0.0   →  requests>=2.32.5

Version Alignment

In monorepos or projects with multiple dependency files, the same package might have different versions:

# requirements.txt
requests==2.28.0

# requirements-dev.txt
requests==2.31.0

# services/api/requirements.txt
requests==2.25.0

upd align updates every occurrence to the highest version found:

upd align              # Align all packages to highest version
upd align --dry-run    # Preview changes
upd align --check      # Exit 1 if misalignments (for CI)
upd align --lang python # Align only Python packages

It only aligns within one ecosystem, skips packages with upper bound constraints (e.g. >=2.0,<3.0) to avoid breaking them, and ignores pre-release versions when finding the highest version.

Pre-commit Integration

Add upd to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/rvben/upd-pre-commit
    rev: v0.0.24
    hooks:
      - id: upd-check
        # Optional: only check specific ecosystems
        # args: ['--lang', 'python']

Available hooks:

Both hooks run on pre-push by default. Uses language: python which installs upd from PyPI automatically, so no manual installation is needed.

Documentation

Everything you look up rather than read lives in docs/.

Releases

Vership workflow, publication guarantees, automated integration pins, and safe retry procedures. → docs/releases.md

Supported files

Every file upd discovers, per ecosystem, plus annotated version pins in files it does not otherwise understand. → docs/ecosystems.md

Comparison and benchmarks

A dated feature matrix for related dependency tools, plus workload-based, reproducible benchmarks that avoid ranking unlike operations. → docs/comparison.md

Security auditing

OSV vulnerability scanning, --fix-audit, SARIF output, and CI integration. → docs/audit.md

Security policy

Private vulnerability reporting, supported versions, trust boundaries, and release integrity. → SECURITY.md

Configuration file

.updrc.toml discovery order and every key it accepts. → docs/configuration.md

Cooldown (minimum release age)

Hold back versions published less than N days ago, per ecosystem or per language, and keep --lock refreshes to the same cooldown. → docs/configuration.md#cooldown-minimum-release-age

Caching

Where the 24-hour version cache lives and how to clear or bypass it. → docs/configuration.md#caching

Environment variables

Every variable upd reads, in one table. → docs/configuration.md#environment-variables

Private repositories

Credential detection for PyPI, npm, Cargo, Go, and GitHub, including private indexes declared in pyproject.toml. → docs/private-registries.md

GitHub pull requests

Run any supported dependency updates as one rolling GitHub PR, with immutable Action SHA verification, validation, artifact reporting, and opt-in auto-merge. → docs/github-actions.md

GitLab merge requests

Run scheduled dependency updates as one rolling GitLab MR, with validation, lease-protected branch updates, and explicitly opt-in GitLab-native auto-merge. → docs/gitlab.md

Stability

The stable CLI surface, exit codes, --lock commands, and output guarantees. → docs/stability.md

Development

# Build
make build

# Run tests
make test

# Lint
make lint

# Format
make fmt

# All checks
make check

License

MIT