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 zaojun.marvin8.zone.

New in v1.6.0: License compliance checking — verify that every dependency's license is compatible with your project's own license. Enable with --check-licenses or check-licenses = true in [tool.zaojun]. The allowed set is auto-derived from project.license (SPDX) or specified explicitly via allowed-licenses. Packages with incompatible licenses show ⚖️ inline and a License Violations block at the end of the report; exit code 1. Use unknown-license = "fail" to reject dependencies with unrecognisable licenses, "allow" to ignore them silently. Exempt individual packages with license-ignore (a reason field is required for each entry). Zero extra HTTP requests — all license data comes from the PyPI response already fetched per dependency.

New in v1.5.0: CVE/vulnerability scanning — zaojun surfaces known security advisories from the PyPI vulnerability feed (zero extra HTTP requests; data comes from the same response already fetched per package). Packages with open advisories show 🔒 inline and a Vulnerabilities detail block at the end of the report. Use vuln-ignore in [tool.zaojun] to suppress specific CVEs, GHSAs, or entire packages by name or version range. Also: --flag-major (default on) — flags compatible major-version bumps with 💥 so they don't get lost among minor updates. --major-ok opts out of exit code 1 for major bumps, mirroring --compat-ok. Also: --index-url URL to point zaojun at Artifactory, devpi, or any PyPI JSON API-compatible index. Cache files are now leaner — the unused package metadata blob has been dropped, reducing per-entry disk use.

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://forge.marvin8.zone/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://forge.marvin8.zone/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