uvbump-cli 1.5.0
CLI to audit uv-managed dependency pins across a workspace
Requires Python: >=3.12
Keywords: cli, dependencies, packaging, uv, versioning

# uvbump (distribution: uvbump-cli)

CLI helper that inspects a uv-managed project (or workspace) and reports which
dependencies can be bumped based on what is pinned in `pyproject.toml`, what is
installed in your lockfile environment, and what is currently available on
PyPI.

## Quick start

1. Install uv: https://docs.astral.sh/uv/.
2. Install uvbump once published: `pip install uvbump-cli` (or `uv tool install uvbump-cli`).
3. From a uv project root, run `uvbump` to print two tables:
   - **Packages out of date**: your pins lag behind the newest versions on PyPI.
   - **Packages can be bumped**: installed versions differ from the versions pinned in `pyproject.toml`.

```
$ uvbump --root .
Packages out of date:
Package Name                                      Installed Version             Project Version               Newest Version                Suggested Action
requests                                         2.32.3                       2.31.0                         2.32.3                        Update package version

Packages can be bumped:
Package Name                                      Installed Version             Project Version               Newest Version                Suggested Action
requests                                         2.32.3                       2.31.0                         2.32.3                        Bump package version in project specification
```

## Usage

```
uvbump --root /path/to/project
```

### Install and run as a uv tool

```
uv tool install uvbump-cli
uvbump --root /path/to/project
```

Examples:

```
# uv workspace (default)
uvbump --root .

# npm project
uvbump --kind npm --root path/to/frontend

# upgrade all dependencies (uv)
uvbump --root . --upgrade

# interactively choose upgrades (npm)
uvbump --kind npm --root path/to/frontend --upgrade --interactive --group-by package

# preview upgrade changes without writing files
uvbump --root . --upgrade --dry-run
```

Common flags:

- `--root` (optional): path to the directory that contains `pyproject.toml` or `package.json`. Defaults to the current working directory.
- `--kind` (optional): `uv` or `npm` (default: `uv`).
- `--timeout` (optional): subprocess timeout in seconds for uv/uvx/npm calls.
- `--upgrade`: rewrite dependency versions to the newest available versions.
- `--interactive`: pick which dependencies to upgrade.
- `--group-by` (interactive only): `workspace` or `package` (default: `workspace`).
- `--dry-run`: preview upgrade changes without writing files.
- `--show-up-to-date`: include dependencies that already match the newest version in upgrade selection.
- `--version`: print the current uvbump version.

The command uses `uv export` and `uvx pip index versions` under the hood for uv projects, so make sure `uv` is on your `PATH`.

## Development

- Run locally with `uv run python -m uvbump --root examples` to exercise the sample workspace in `examples/`.
- Formatting/linting is handled by ruff; run `ruff check` and `ruff format` as needed.

## Docker test harness

- Build an image that prepares custom mismatched environments: `docker build -t uvbump-tests .`
- Version scenarios are driven by Jinja templates:
  - Edit `examples/version.env` for the pin you want in `pyproject.toml.jinja` files and the install versions you want in the environment.
  - On container start the entrypoint sources that env file, renders each `*.jinja` under `examples/` into `pyproject.toml`, and installs the requested runtime packages.
- Run a sample check: `docker run --rm -e VERSION_ENV=/app/examples/version.env uvbump-tests python -m uvbump --root examples`
- Opt out of installs with `SKIP_INSTALL=1`, skip template rendering with `SKIP_TEMPLATE_RENDER=1`, or skip the whole version step with `SKIP_VERSION_CONFIG=1`.

## Building & publishing to PyPI

1. Build artifacts: `uv build` (uses Hatchling under the hood).
2. Verify contents: inspect `dist/` for the wheel and sdist.
3. Publish (after configuring credentials): `uv publish --token <pypi-token>` or `python -m twine upload dist/*`.

The project metadata lives in `pyproject.toml`; update the version there before each release.