Catch incompatible dependency licenses before they block a release

A verdict, not a list · Transitive across 10 ecosystems · No dependency installs

Quick start · CI integration · Claude Code skill · How it decides · Security model · Documentation

^{Illustrative packages. The report is licenseal's own output.}

licenseal is a fast license compatibility checker for dependency trees across language ecosystems. It reads manifests, lockfiles, and public registry metadata and tells you whether your dependency licenses are compatible with the license you ship under, fast enough to run in CI. It does not install dependencies, run package-manager commands, execute build scripts, or download package archives.

uvx licenseal check

Not legal advice. licenseal automates dependency-license discovery and compatibility classification. It is a CI/audit aid, not a substitute for legal review.

Why it matters

License non-compliance is a quiet delivery risk: it usually does not break the build, but it can block a shipment, customer approval, funding round, or acquisition when discovered late.

[!NOTE]
In a benchmark of 50 widely used open-source repositories across ten ecosystems, licenseal flagged 485 license-compatibility issues at default settings — 405 warnings and 80 outright violations, spanning 9 of the 10 ecosystems — each a dependency whose license needed compatibility review against the project's own declared license. Inventory-only license tools surface none of these.

Public engineering policies and case history show why dependency-license checks matter. Google and Power publish restrictive guidance for licenses such as AGPL and SSPL, while Salesforce and Uber have written about license review in production software governance. GPL enforcement cases such as Artifex v. Hancom and Software Freedom Conservancy v. Vizio also show that dependency-license obligations can become real delivery and legal risk.

How it works

licenseal reads the manifests and lockfiles in your repository, resolves the transitive dependency tree, looks up each package's license in public registry metadata, and compares it with your project's license. You get a CI verdict, a Markdown or JSON report, and checked-in review overrides.

Supported ecosystems

The manifests, lockfiles, and registries read for each are listed under Supported ecosystems.

Quick start

# Run once, without installing licenseal
uvx licenseal check

# Install the CLI
uv tool install licenseal    # or: pipx install licenseal

# Or add it to a Python project
uv add --dev licenseal       # or: pip install licenseal

The exit code is non-zero when there are unreviewed violations, warnings, unknown licenses, or analysis gaps (something the scan could not read, such as a manifest without an up-to-date lockfile). Commit the lockfile, or pass --no-require-lockfile to accept versions estimated from the registry.

Defaults worth knowing:

• The whole dependency tree is scanned, without dev dependencies. --no-transitive scans direct dependencies only; --dev adds dev dependencies.
• Violations always fail. Warnings, unknown licenses, and analysis gaps fail too, unless you pass --no-strict.
• The project license is read from a manifest in the scanned directory, never from a nested package. If that does not give a recognised license, the project is checked as Proprietary: permissive dependencies pass, copyleft ones are flagged (details).

Every flag is in the CLI reference.

[!NOTE]
Upgrading from 0.4.x? 1.0.0 finds dependencies that 0.4.x missed and reads licenses more strictly, so a check that passed can fail with no change to your project. Follow the migration guide, or point a coding agent at llms.txt, the index of the documentation.

CI integration

# .github/workflows/licenseal.yml
name: License compatibility
on: [push, pull_request]
jobs:
  licenseal:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/[email protected]
      - run: uvx licenseal check

For a PR comment or an audit trail, write a report with -f markdown -o LICENSES.md or -f json -o report.json (schema). The file is written even when findings or analysis gaps fail the check, so CI can publish it. This repository commits its own report as LICENSES.md.

Reviewing findings

When a dependency is flagged but you have better license information than the scan found, record the reviewed license in a checked-in licenseal.review.toml. licenseal init-review-file scaffolds an entry for each flagged dependency. A review can only override a flagged dependency, and a reviewed dependency stays in the report with both its detected and its reviewed license. The workflow, the file format, and its rules are in Review flagged dependencies.

Claude Code review skill

CI can tell you which dependency licenses need attention; the bundled Claude Code skill helps turn those findings into documented decisions. Install it in the project being audited, then run /licenseal-review in Claude Code:

licenseal install-skill

The skill runs licenseal check, walks through warnings, violations, unknown licenses, and analysis gaps, and asks how your project is distributed, hosted, modified, or shipped. It fills licenseal.review.toml only when there is a concrete reviewable rationale, keeps genuine incompatibilities flagged, and re-runs the check so what is still flagged is explicit.

How licenseal decides

licenseal gives each dependency license a risk level and compares it with your project's license:

MIT, BSD, and Apache-2.0 are permissive; LGPL, MPL-2.0, and EPL are weak copyleft; GPL is strong copyleft; AGPL is network copyleft. A license that cannot be classified, such as a source-available one, or a package with no license metadata, is Unknown and goes to manual review. The rules for specific license pairs, for OR / AND / WITH expressions, and for dev dependencies are in How licenseal decides.

How it compares

Comparison last reviewed: June 2026. Tool capabilities change; check each project before making a buying or compliance decision.

✓ supported · ~ partial · - not supported

No tool clears every row. The discovery row is about source-tree analysis: manifests, lockfiles, and registry metadata before a successful package-manager install is assumed. Some tools can produce broader inventories after installation or hosted analysis. ~ means the capability exists, but with a different workflow, hosted service, package-manager prerequisite, or policy model. The speed row reflects benchmark runs on public repositories, not a vendor guarantee. Pair licenseal with an SBOM generator, hosted compliance platform, or installed-metadata scanner when those are the artifacts or workflows you need.

Scope

licenseal is intentionally narrow:

• It is a license compatibility checker, not a legal approval workflow, a vulnerability scanner, or an SBOM generator.
• It reads manifests, lockfiles, and public registry metadata only. A package pinned to a private registry is looked up on the public one by name (what leaves the process). A dependency installed from git, a URL, or a path the scan does not read is reported as UNKNOWN, and nothing is requested for it (off-registry dependencies).
• It does not infer licenses from LICENSE files or source comments: missing structured metadata is UNKNOWN and goes to manual review.
• A review records a maintainer's decision. It is an audit record, not legal sign-off.

The trust boundary and the network allowlist are in the security model.

Documentation

The documentation is at licenseal.shcherbak.ai, with an index for language models and coding agents at llms.txt:

• Quick start and reading the report
• Run it in CI and fix a failing check
• What fails a check and how licenseal decides
• Supported ecosystems, with a page for each
• CLI reference and the JSON report
• Security model: what is read, which hosts are contacted, and what is sent
• Changelog

Contributing

See CONTRIBUTING.md for development setup and guidelines. If licenseal helps your project, star ⭐ this repo to help other teams find it too.

License

Apache-2.0. See LICENSE for the full text and NOTICE for attribution.

More from shcherbak_ai

Structured extraction from documents with LLMs.

Network egress control for CLI tools and agent workflows.

Questions or collaboration ideas? Reach out on LinkedIn or X. Built with ❤️ in Oslo, Norway.