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:
| Project \ Dependency | Permissive | Weak Copyleft | Strong Copyleft | Network Copyleft |
|---|
| Permissive | OK | Warning | Violation | Violation |
| Weak Copyleft | OK | OK | Violation | Violation |
| Strong Copyleft | OK | OK | OK | Warning |
| Network Copyleft | OK | OK | OK | OK |
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.
| Capability | licenseal | pip-licenses | license-checker | LicenseFinder | fossa-cli |
|---|
| Project-license compatibility verdict | ✓ | - | - | ~ | ~ |
| Transitive discovery, no dependency install or build | ✓ | - | - | - | ~ |
| Fast, seconds-scale CI path | ✓ | ~ | ~ | - | - |
| Agent-assisted flagged-finding review | ✓ | - | - | - | - |
| Manual review override file | ✓ | - | ~ | ✓ | ~ |
| Multiple ecosystems in one tool | ✓ (10) | - | - | ✓ | ✓ |
| Local-only full workflow, no hosted service | ✓ | ✓ | ✓ | ✓ | - |
| Offline operation | - | ✓ | ✓ | ~ | - |
| Standards SBOM export (CycloneDX / SPDX) |
✓ 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:
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
Questions or collaboration ideas? Reach out on LinkedIn or X. Built with ❤️ in Oslo, Norway.
