bump-minimum-dependencies

Automatically bump the minimum allowed versions of dependencies in pyproject.toml based on the time since first release, with a cooldown period. ⬆️

Inspired by SPEC 0. 🧪

Motivation

Determining the minimum requirements of a Python package requires balancing competing tradeoffs. Lengthy support windows increase maintenance burden, prevent developers from using new features and assuming bugfixes, and lead to more complicated code. Short support windows increase the risk of dependency conflicts. Automatically bumping minimum requirements in a predictable way saves time and balances these tradeoffs.

Usage

Usage: bump-minimum-dependencies [OPTIONS]

  Bump minimum versions of dependencies in pyproject.toml.

  This tool updates pyproject.toml via `uv add --frozen` to drop support for
  minor versions of package dependencies based on the time since the minor
  version was first released, where package versions may be given by
  `<MAJOR>.<MINOR>` or `<MAJOR>.<MINOR>.<MICRO>`. Exact version specifiers and
  upper limits are preserved.

  For pre-1.0 version numbers or when a `<MAJOR>.<MINOR>` release has numerous
  micro releases, `<MICRO>` will be bumped to the last micro release prior to
  the drop date.

  Existing requirements will not be changed when the new minimum version is
  incompatible with old requirements, a requirement has markers, or there are
  multiple `!=` exclusions in the combined requirement.

  "Groups" refers to dependency groups while "extras" refers to categories of
  optional dependencies.

Options:
  --pyproject-file FILE           Path to pyproject.toml.  [default:
                                  pyproject.toml]
  --drop-months FLOAT RANGE       Drop minor releases older than this many
                                  months ago.  [default: 24; x>=0]
  --cooldown-months FLOAT RANGE   Keep at least one minor release this old
                                  when possible.  [default: 21; x>=0]
  --only-package TEXT             Name of a package to update. May be provided
                                  multiple times. When this option is used,
                                  all other packages will be skipped.
  --skip-package TEXT             A package to skip when performing updates.
                                  Can be used multiple times.
  --no-extras                     Do not update extras, except if specified by
                                  --only-extra.
  --only-extra TEXT               An extra to update. Can be used multiple
                                  times. Implies --no-extras, --no-groups, and
                                  --skip-core.
  --skip-extra TEXT               An extra to not be updated. Can use multiple
                                  times.
  --only-group TEXT               A dependency group to update. Can use
                                  multiple times. Implies --no-groups, --no-
                                  extras, and --skip-core.
  --no-groups                     Do not update dependency groups, except if
                                  specified by --only-group.
  --skip-group TEXT               A dependency group to skip. Can use multiple
                                  times.
  --skip-core                     Do not update core project dependencies.
  --dry-run                       Instead of performing updates, print the uv
                                  commands that would be run.
  --verbosity [DEBUG|INFO|WARNING|ERROR|CRITICAL|NOTSET]
                                  Logging verbosity level.  [default: WARNING]
  --version                       Show the version and exit.
  --help                          Show this message and exit.

Examples

To bump core project dependencies, optional dependencies, and dependency groups with the default settings, run:

bump-minimum-dependencies

To bump only plasmapy, run:

bump-minimum-dependencies --only-package plasmapy

To skip updates for numpy and plasmapy, run:

bump-minimum-dependencies --skip-package numpy --skip-package plasmapy

To drop minor versions older than 36 months with a cooldown of 24 months, run:

bump-minimum-dependencies --drop-months 36 --cooldown-months 24

To bump core project dependencies but skip bumping optional dependencies and dependency groups, run:

bump-minimum-dependencies --no-extras --no-groups

To bump project dependencies, optional dependencies, and all but the doc dependency group, run:

bump-minimum-dependencies --skip-group doc

To bump only dependency groups, run:

bump-minimum-dependencies --skip-core --no-extras

To bump only the test dependency group and skip updates to core project dependencies, optional dependencies, and other dependency groups, run:

bump-minimum-dependencies --only-group=test

Usage notes

• Please review and test all updates to pyproject.toml before accepting them.

  • Use uv's lowest-direct resolution strategy to run tests in an environment containing the minimum versions of direct dependencies.

• This tool invokes uv add --frozen to update dependencies in pyproject.toml without updating lock files or syncing virtual environments. Requirements may be normalized upon updates.

• Using dep-logic allows bump-minimum-dependencies to handle a wide variety of requirements specifiers and perform logical operations to combine multiple requirements specifiers. For example, >=4.1,<5 and >=4.2 will be combined into >=4.2,<5.

  • If the time-based requirement is mutually exclusive with the original requirement, the original requirement will be preserved.

• Requirements that cannot be updated will be skipped.

Limitations and caveats

• This tool does not guarantee that an environment can be created that includes the minimum allowed versions of all direct dependencies, but this can be tested with uv lock --resolution=lowest-direct --dry-run.

• Requirements that use ==, ~=, or multiple != comparisons or non-standard version specifiers might not be updated.

• This tool does not update build-system.requires or requirements with markers (such as 'setuptools; python_version > "3.11"').

Feature requests and bug reports

To make a feature request, please raise an issue.

If you discover a bug, please raise an issue with a minimal reproducible example (i.e., the pyproject.toml file and the bump-minimum-dependencies command that was used).

Related projects

• scientific-python/spec0-action — a GitHub action to create quarterly pull requests to perform SPEC 0 updates using a published drop schedule. Unlike bump-minimum-dependencies, this tool distinguishes between SPEC 0 core packages and other packages.

• cgordberg/bump-dependencies — updates dependency specifiers in pyproject.toml to latest compatible versions.

• hmaarrfk/nep29 — calculator tools for NEP 29, a precursor to SPEC 0. nep29 can be used to check the results of bump-minimum-dependencies, as in the following example (if uv is installed):

  uvx --python=3.14 --with=setuptools nep29 --n_minor=1 --n_months=12 scipy