molt

Changeset-driven versioning, changelogs, and publishing for Python packages and monorepos. Built on PEP 440 versions and PEP 508 requirements, and on the way pip and uv actually resolve them.

Documentation

Install

The distribution is molt-release. The command it installs is molt.

uv tool install molt-release
molt --help

pipx install molt-release and pip install molt-release work too, and uvx molt-release --help runs it without installing anything. Requires Python 3.11 or newer, on Windows, macOS, or Linux.

The release loop

You record the intent of a change while you write it. A separate step turns accumulated intent into releases.

molt init                 # one time: create .changeset/ and a [tool.molt] block
# ... make a change ...
molt add                  # record which packages changed, and how much
molt version              # bump versions, write changelogs, update the lockfile
git commit -am "Release"
molt publish              # build, upload to PyPI, tag

molt add writes a small Markdown file you commit alongside your code:

---
"acme-core": minor
---

Add a --stream flag to the export API for large datasets.

molt version consumes every pending changeset in one pass, takes the highest bump per package, folds the summaries into each CHANGELOG.md, and deletes the files it consumed. All mutations are buffered and flushed together, so a mid-run failure never leaves a repository half-versioned.

Monorepo propagation

In a workspace, a changeset for one package cascades to the packages that depend on it. Given acme-cli requiring acme-core>=1.2.0,<2.0.0, a major bump to acme-core plans this:

$ molt status
Packages to be bumped:
- major
  - acme-core   1.2.0 -> 2.0.0
- patch
  - acme-cli    0.5.0 -> 0.5.1   (dependency bump)

acme-cli has no changeset of its own. Version 2.0.0 falls outside its constraint, so it needs a release. Molt gives it the smallest bump that does the job and rewrites the constraint to >=2.0.0,<3.0.0. A minor bump to 1.3.0 would have released nothing extra, because 1.3.0 still satisfies the range.

See Dependency propagation.

Commands

--dry-run prints the plan for any mutating command and writes nothing. --non-interactive resolves every prompt to its documented default, which is what Dependabot, Renovate, and codegen need. Human-facing output goes to stderr and stdout carries machine-readable payloads only, so molt status --output json | jq '.releases[].name' needs no filtering.

Full reference: CLI.

Python specifics

Python's packaging rules shape several of molt's behaviors.

• PEP 440 version math, through packaging. Prereleases are 1.0.0rc1, 1.0.0a2, or 1.0.0.dev3 from a fixed set of spellings, and package names compare under PEP 503 normalization.
• Prerelease is a flag, not a persistent mode: molt version --pre rc. There is no state file to enter, commit, or exit.
• uv.lock is refreshed when molt version bumps a package, so a --frozen or --locked install in CI still resolves against the release commit. uv workspaces are first-class; other backends sit behind an ecosystem seam.
• Snapshots target a separate index. PyPI versions are permanent, so a snapshot on the public index would burn a version number for good.
• A bad release is yanked, not unpublished. molt yank verifies the version, reports whether it is already yanked, and prints the exact steps. PyPI publishes no yank API, so the final click is yours.

Continuous integration

The repository root carries a composite GitHub Action that runs the whole loop. It keeps a "Version Packages" pull request in sync with your pending changesets, then builds, publishes, tags, and creates a GitHub Release per package once that pull request merges.

- uses: giancarlosisasi/molt@<sha>
  with:
    molt-version: "0.1.0"
    publish: molt publish
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

See CI: GitHub Action for the full workflow, its inputs, and its outputs. Nothing in the loop is GitHub-specific: the same molt commands drive it anywhere.

Documentation

• Overview and The changeset workflow
• Installation, single-package quickstart, monorepo quickstart
• The release plan and Versioning and PEP 440
• Configuration and every option
• Migrating from changesets

Acknowledgements

Molt's workflow comes from changesets, the release tool for JavaScript monorepos. Its version math comes from packaging, the PyPA reference implementation of PEP 440 and PEP 508. Full credits, including the prior work in Python and the related tools worth comparing molt against, are on the Acknowledgements page.

License

MIT.