GitHub License Scanner

Analyze GitHub repo licenses + dependencies
Know if you can sell closed-source — or if copyleft (GPL / AGPL) forces open source.
NiceGUI web UI · CLI · bilingual ES/EN · light & dark mode

Website: nezbit.github.io/github-license-scanner · install with pipx or clone from GitHub

Screenshots

Light workspace (full-width layout)

Dark mode

How it works

Features

• Repo license via GitHub REST API
• Dependency scan for package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, Gemfile, composer.json, Maven/Gradle (best-effort)
• Registry license lookup (npm, PyPI, crates.io, RubyGems, Packagist)
• Risk colors: green (permissive) · orange (weak/unknown) · red (strong copyleft)
• Closed-source sellability signal + GPL/AGPL force-open flag
• Permissive replacement suggestions for problematic packages
• Batch mode (many URLs) + scan history
• Copy copyright notice button
• Deploy advisor (Vercel, Railway, Render, Fly.io, …)
• ES / EN UI · light / dark theme · full-width responsive layout

Website (GitHub Pages)

Static landing (install / clone links only — the scanner runs on your machine):

https://nezbit.github.io/github-license-scanner/

Quick start

pipx install github-license-scanner
gls scan psf/requests

The web interface is an optional extra, so the CLI stays light:

pipx install 'github-license-scanner[ui]'
gls ui

Optional configuration (recommended):

# PowerShell example
$env:GITHUB_TOKEN = "ghp_..."
$env:GLS_STORAGE_SECRET = "long-random-string"

Environment variables are the source of truth. A .env file is only a local convenience: one is read from the current directory or from your user config directory if present, and real environment variables always win.

See .env.example for the full list.

History and users live in your per-user data directory, never inside the installed package:

Multi-user auth + private history

gls user-add alice          # interactive password (≥8 chars)

export GLS_AUTH_ENABLED=1
export GLS_STORAGE_SECRET=long-random-string

Each user gets history/<username>.json in that data directory. Without auth, history stays in a single history.json.

Web UI

pipx install 'github-license-scanner[ui]'
gls ui                       # or: gls ui --host 0.0.0.0 --port 9000

Open http://127.0.0.1:8080 (binds to localhost by default)

• Switch ES | EN in the top bar
• Toggle light / dark with the sun/moon button
• Try example chips (psf/requests, encode/httpx, …)

CLI

# Single repository
gls scan https://github.com/psf/requests

# Shorthand
gls scan psf/requests

# Batch (one URL per line)
gls batch urls.example.txt

# History
gls history

# Markdown + SBOM export
gls scan psf/requests --markdown report.md --sbom bom.cdx.json
gls scan psf/requests --sbom bom.spdx.json --sbom-format spdx

github-license-scanner is available as a longer alias for gls.

Project layout

github-license-scanner/
├── pyproject.toml          # Packaging (hatchling)
├── gls/
│   ├── __init__.py         # __version__
│   ├── cli.py              # Command-line mode + entry point
│   ├── webui.py            # NiceGUI interface (optional [ui] extra)
│   ├── config.py           # Env-based configuration + data paths
│   ├── rate_limit.py       # Scan rate limiter
│   ├── auth.py             # Optional multi-user auth (PBKDF2)
│   ├── spdx_engine.py      # SPDX expression parser + risk
│   ├── sbom_export.py      # CycloneDX 1.5 + SPDX 2.3 JSON
│   ├── github_api.py       # URL parse + GitHub REST
│   ├── dependency_scanner.py  # Manifest parsers
│   ├── license_analyzer.py    # Registry licenses + verdict
│   ├── deploy_advisor.py   # Deploy recommendations
│   ├── history_store.py    # JSON history (shared or per-user)
│   ├── models.py           # Dataclasses
│   ├── i18n.py             # ES/EN strings
│   ├── report.py           # Markdown export
│   └── docs/               # Legal pages served by the web UI
│       ├── LEGAL_DISCLAIMER.md
│       ├── PRIVACY.md
│       └── TERMS.md
├── scripts/                # Dev smoke tests / audit tooling
├── .env.example
├── urls.example.txt
└── docs/
    ├── AUDIT_REPORT.pdf
    └── images/             # README screenshots

License risk legend

Security & privacy notes

• Default bind is localhost only (GLS_HOST=127.0.0.1).
• Set a strong GLS_STORAGE_SECRET before exposing the UI.
• Scan history is instance-local and shared if multi-user — use Clear history or prune via config.
• Rate limits and batch caps reduce GitHub API abuse.
• Docs: Privacy · Terms · Legal disclaimer

Disclaimer

This tool provides automated heuristics only. It is not legal advice and not a
license-compatibility opinion. Dual-licensing, linking models, SaaS (AGPL/SSPL),
attribution duties, and contracts can change obligations.
Always review with a qualified attorney before commercial closed-source distribution.
See gls/docs/LEGAL_DISCLAIMER.md.

Development

git clone https://github.com/NezbiT/github-license-scanner.git
cd github-license-scanner

python -m venv .venv
.venv\Scripts\activate          # macOS / Linux: source .venv/bin/activate

pip install -e '.[ui]'
python -m gls.cli scan psf/requests

Build and check a release locally before tagging:

pip install build twine
python -m build
twine check dist/*

Releases are published to PyPI by .github/workflows/publish.yml using Trusted Publishing (OIDC) — no API tokens are stored anywhere.

License

Released under the MIT License.

You may use, modify, and redistribute this project commercially or privately,
as long as you keep the copyright and license notice. See LICENSE for full text.

The MIT license applies to this tool’s source code.
It does not change the licenses of the GitHub repositories or packages you scan.

Made with NiceGUI · httpx · packaging