zaojun 1.4.0

Checks project dependencies for newer versions.

zaojun

zaojun is a command-line (CLI) tool to check versions of your dependencies as defined in pyproject.toml against the latest versions published on PyPI. Full documentation is available at marvin8.codeberg.page/zaojun.

New in v1.4.0: JSON output via --format json — machine-readable dependency status for scripts and CI pipelines. Also: persistent defaults via [tool.zaojun] in pyproject.toml — set cache, groups, min-age, library, format, and more without repeating CLI flags. CLI flags always override config.

New in v1.3.0: Library mode via --library — checks that version constraints are consumer-friendly (no exact pins, no tight upper bounds) and only flags updates that fall outside the allowed range. Compatible updates are silent when the latest version already satisfies the spec.

New in v1.2.0: Supply-chain quarantine via --min-age N — ignore updates younger than N days, giving the ecosystem time to react to compromised releases. Updates that are too new show ⏳ and don't trigger exit code 1.

New in v1.0.0: PyPI API response caching for faster repeated checks! Enable with --cache for 10-100x performance improvements on subsequent runs.

Install and run from Source

Alternatively, you can run zaojun from source by cloning the repository:

git clone https://codeberg.org/marvin8/zaojun.git

zaojun uses uv for dependency control; please install uv before proceeding.

Install all required Python modules:

uv sync

Run zaojun with:

uv run zaojun

Try the new caching feature for faster repeated checks:

uv run zaojun --cache --cache-stats

As a pre-commit hook

Add the following snippet to your .pre-commit-config.yaml:

- repo: https://codeberg.org/marvin8/zaojun
  rev: 1.2.0
  hooks:

- id: zaojun
      args:
        "--groups"
        "--cache"  # Enable caching for faster runs

Significance of the name zaojun

Zao Jun is the Chinese god who acts as a household guardian, overseeing domestic harmony and reporting family conduct to the heavens—reinforcing moral behavior within the kin unit. This tool tries to keep your project and its dependencies in harmony. It doesn’t report to any third parties, though :)

I know it’s a bit far-fetched, but I like it—so there!

If you’d like to learn more about Zao Jun, the Chinese Kitchen God:

• Wikipedia
• Columbia University

Licensing

zaojun is licensed under the GNU Affero General Public License v3.0.

Supporting zaojun

You can support zaojun in several ways:

• Create an issue for problems or ideas you have.
• Create a pull request if you prefer a hands-on approach.
• Buy me a coffee.
• Send small change in Monero to the address below:

Monero donation address

88xtj3hqQEpXrb5KLCigRF1azxDh8r9XvYZPuXwaGaX5fWtgub1gQsn8sZCmEGhReZMww6RRaq5HZ48HjrNqmeccUHcwABg