py-license-auditor

The fastest license auditor for uv projects - Built specifically for the modern Python ecosystem.

🎯 uv-First Strategy: This tool is designed exclusively for uv projects. We focus on providing the best possible experience for uv users rather than supporting all package managers.

✨ Why uv + py-license-auditor?

• 🚀 Built for Speed: Both tools are written in Rust for maximum performance
• 🎯 uv-Native: Deep integration with uv.lock and uv workflows
• 🔧 Zero Config: Works out of the box with uv projects
• ⚡ Fast Workflow: uv sync && py-license-auditor check - that's it!

🚀 Installation

For uv Users (Recommended)

# Install as a uv tool
uv tool install py-license-auditor

# Use in any uv project
cd my-uv-project
uv tool run py-license-auditor check

Manual Installation

Download the binary for your platform from GitHub Releases.

From Source

git clone https://github.com/yayami3/py-license-auditor
cd py-license-auditor
cargo install --path .

📖 Usage

📚 Quick Start: See QUICKSTART.md for a step-by-step guide

Quick Start

# 1. Setup your uv project
uv init my-project
cd my-project
uv add requests pandas

# 2. Configure license policy (one-time setup)
py-license-auditor init green

# 3. Run license audit
uv sync
py-license-auditor check

Configuration Setup

Initialize with Built-in Policies

# For commercial/enterprise projects (safest)
py-license-auditor init green

# For balanced development (permissive + weak copyleft)
py-license-auditor init yellow

# For audit/OSS development (information gathering)
py-license-auditor init red

This creates a [tool.py-license-auditor] section in your pyproject.toml with appropriate settings.

Basic Usage

# Auto-detect .venv in current directory (shows table format by default)
py-license-auditor check

# Specify site-packages directory
py-license-auditor check /path/to/site-packages

# Save to file
py-license-auditor check --output licenses.json

Output Formats

# Table for terminal viewing (default)
py-license-auditor check --format table

# JSON for programmatic use
py-license-auditor check --format json

# CSV for spreadsheets
py-license-auditor check --format csv

Advanced Options

# Include packages without license info
py-license-auditor check --include-unknown

# Combine options
py-license-auditor check --format csv --output report.csv --include-unknown

# Automatic violation fixing
py-license-auditor fix --dry-run  # Preview changes
py-license-auditor fix            # Apply exceptions

# Global options
py-license-auditor --quiet check
py-license-auditor --verbose check

📊 Output Example

Table Format (Default)

📦 License Summary (20 packages)
✅ 20 with licenses  ⚠️ 0 unknown  🚫 2 violations

🔍 Issues Found:
┌─────────────────┬─────────┬─────────────┬─────────────────┐
│ Package         │ Version │ License     │ Problem         │
├─────────────────┼─────────┼─────────────┼─────────────────┤
│ some-gpl-lib    │ 2.1.0   │ GPL-3.0     │ Not allowed     │
│ another-package │ 1.0.0   │ AGPL-3.0    │ Not allowed     │
└─────────────────┴─────────┴─────────────┴─────────────────┘

💡 Run with --verbose to see all 20 packages

JSON Format

{
  "packages": [
    {
      "name": "requests",
      "version": "2.31.0",
      "license": "Apache-2.0",
      "license_classifiers": [
        "License :: OSI Approved :: Apache Software License"
      ],
      "metadata_source": "METADATA"
    }
  ],
  "summary": {
    "total_packages": 50,
    "with_license": 45,
    "without_license": 5,
    "license_types": {
      "osi_approved": {
        "MIT": 20,
        "Apache-2.0": 15,
        "BSD": 8
      },
      "non_osi": {
        "MIT License": 2
      }
    }
  },
  "violations": {
    "total": 2,
    "errors": 1,
    "warnings": 1,
    "details": [
      {
        "package_name": "some-gpl-lib",
        "package_version": "2.1.0",
        "license": "GPL-3.0",
        "violation_level": "Forbidden",
        "matched_rule": "exact: GPL-3.0",
        "message": "License 'GPL-3.0' is forbidden by policy"
      }
    ]
  }
}

CSV Format

name,version,license,license_classifiers,metadata_source
requests,2.31.0,Apache-2.0,"License :: OSI Approved :: Apache Software License",METADATA
click,8.1.7,BSD-3-Clause,"License :: OSI Approved :: BSD License",METADATA

🎛️ Policy Configuration

Built-in Policies

Three ready-to-use policies are included:

# Green: Safe for commercial use - only permissive licenses
py-license-auditor init green

# Yellow: Balanced policy - permissive + weak copyleft
py-license-auditor init yellow

# Red: Audit mode - all licenses allowed for information gathering
py-license-auditor init red

Custom Policy Configuration

After running py-license-auditor init, you can customize the generated configuration in pyproject.toml:

[tool.py-license-auditor]
format = "json"
include_unknown = true
fail_on_violations = true

[tool.py-license-auditor.policy]
name = "Custom License Policy"
description = "Tailored policy for our project"

[tool.py-license-auditor.policy.allowed_licenses]
exact = ["MIT", "Apache-2.0", "BSD-3-Clause", "ISC"]
patterns = ["BSD-*"]

[tool.py-license-auditor.policy.forbidden_licenses]
exact = ["GPL-3.0", "AGPL-3.0"]
patterns = ["GPL-*", "AGPL-*"]

[tool.py-license-auditor.policy.review_required]
exact = ["MPL-2.0"]
patterns = ["LGPL-*"]

[[tool.py-license-auditor.policy.exceptions]]
name = "legacy-package"
version = "1.0.0"
reason = "Approved by legal team for legacy compatibility"

Policy Rules

• allowed_licenses: Licenses that are automatically approved
• forbidden_licenses: Licenses that cause build failures
• review_required: Licenses that need manual review (warnings)
• exceptions: Package-specific overrides with justification

Pattern Matching

Use glob patterns for flexible license matching:

• "GPL-*" matches GPL-2.0, GPL-3.0, etc.
• "BSD-*" matches BSD-2-Clause, BSD-3-Clause, etc.

🎯 Use Cases

License Compliance

Generate comprehensive reports for legal review and compliance auditing.

# Generate compliance report
py-license-auditor check --format json --output compliance-report.json

CI/CD Integration

Automate license checking in your deployment pipeline.

# GitHub Actions example
- name: Setup License Policy
  run: py-license-auditor init green
  
- name: License Check  
  run: py-license-auditor check
    
- name: Generate License Report
  run: py-license-auditor check --format json --output license-report.json

Dependency Auditing

Understand your project's license obligations and risks.

# Focus on potential issues
py-license-auditor check --format json

🔍 License Categories

The tool categorizes licenses into two groups:

• OSI Approved: Licenses approved by the Open Source Initiative (legally vetted)
• Non-OSI: Custom licenses, proprietary licenses, or unrecognized formats

This helps you quickly identify which licenses need manual legal review.

🛠️ Development

Building from Source

git clone https://github.com/yayami3/py-license-auditor
cd py-license-auditor
cargo build --release

Running Tests

cargo test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🙏 Acknowledgments

• Built with Clap for CLI parsing
• Uses Serde for serialization
• Inspired by the need for better Python license compliance tools