bumpuv

English | 日本語

A CLI tool similar to npm version and uv version --bump written in Python. uv version --bump with added git processing. Reference: npm-version

Performs npm version-like operations on pyproject.toml files for Astral uv (and poetry, etc. PEP 621 compliant tools). Primarily used for triggering GitHub Actions.

Installation and Usage

# Using uv
uv add bumpuv --dev
uv run bumpuv <options>

# Or
uvx bumpuv <options>

# Or
uv tool install bumpuv
bumpuv <options>

# Using pip
pip install bumpuv
bumpuv <options>

# Using poetry
poetry add --group dev bumpuv
poetry run bumpuv <options>

Usage

bumpuv [<newversion> | major | minor | patch | bump] [-n|--dry-run] [-V|--version] [-h|--help]

Arguments

• <newversion>: Explicit version specification (e.g., 1.2.3, 2.0.0a1, 1.0.0rc1)
• major | minor | patch | bump: Version bump type

Version Update Types

• major: Increment major version by 1 (1.2.3 → 2.0.0)
• minor: Increment minor version by 1 (1.2.3 → 1.3.0)
• patch: Increment patch version by 1 (1.2.3 → 1.2.4)
• bump: Default. Same as patch for normal versions, increment number by 1 for pre-release versions (1.2.3a1 → 1.2.3a2)
• <newversion>: Explicit version specification (converted to PEP 440 compliant format)

Options

• -n, --dry-run: Show what would be done without making changes. No prior commit required
• -V, --version: Show version information
• -h, --help: Show help message

Examples

Basic Usage

# Increment patch version (1.0.0 → 1.0.1)
bumpuv patch

# Increment minor version (1.0.1 → 1.1.0)
bumpuv minor

# Increment major version (1.1.0 → 2.0.0)
bumpuv major

# Default behavior (same as bump)
bumpuv

Explicit Version Specification

# Set to specific version
bumpuv 1.5.0

# Set to pre-release version
bumpuv 2.0.0a1

# Release candidate
bumpuv 1.0.0rc1

Pre-release Version Management

# Increment pre-release number (1.0.0a1 → 1.0.0a2)
bumpuv bump

# From pre-release to stable (explicit specification)
bumpuv 1.0.0

Dry-run Mode

# Check changes (no actual changes made)
bumpuv patch -n
bumpuv minor --dry-run

Output Examples

$ bumpuv patch
Updated: /path/to/project/pyproject.toml
Version: 1.0.0 → 1.0.1
Commit: 1.0.1
Tag: v1.0.1

$ bumpuv 2.0.0a1
Updated: /path/to/project/pyproject.toml
Version: 1.0.1 → 2.0.0a1
Commit: 2.0.0a1
Tag: test-2.0.0a1

Specification

Basic Behavior

• Default is equivalent to bumpuv bump
• PEP 440 compliant version management
• Same version and downgrades are not allowed
  • Downgrade example: 1.0.0 > 1.0.0a1
• Switching between pre-release and normal versions requires explicit version specification
  • Example: 1.0.0 → 1.1.0a1 requires bumpuv 1.1.0a1
  • Example: 1.0.0a1 → 1.0.0 requires bumpuv 1.0.0

Git Integration

• Important: All changes must be committed beforehand
• After updating pyproject.toml in current directory, automatically commits and creates tags
  • Commit message: New version number
  • Tag: v{version} for normal versions, test-{version} for pre-release versions
• Does not perform git push. You must manually run git push and git push --tags

Error Conditions

• pyproject.toml does not exist in current directory
• project.version does not exist or is not PEP 440 compliant
• Not a git repository
• Uncommitted changes exist (warning only in dry-run mode)

Limitations

• Configuration files not supported
• Monorepo support not implemented

Similar Tools

• npm-version
• uv version --bump option
• pybump
• bump2version
• bump-my-version
• bumpver

Development

Setup

uv sync

Task Execution

# Run tests
poe test

# Lint
poe check

# Type check
poe mypy

# Run all checks & build & smoke test
poe build

Development Requirements

• uv
• Python == 3.12, 3.10 (for test)

License

MIT