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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
