pip-license-checker

License compliance tool. Detect license names and types for Python
PyPI packages. Identify license types for given license names obtained
by third-party tools. Great coverage of free/libre and open source
licenses of all types:
public domain,
permissive,
copyleft.

Supported formats:

• Python: packages or requirements.txt (detect license name and license type)
• Clojure: EDN files generated by lein-licenses (detect license type)
• JavaScript: CSV files generated by license-checker (detect license type)
• iOS: Apple Plist files generated by CocoaPods Acknowledgements plugin (detect license type)
• Android: JSON files generated by Gradle License Plugin (detect license type)
• Other: CSV files with package name and license name columns (detect license type).

Installation

You can install pip-license-checker either by pulling a Docker
image, builing from the source code or plugging-in GitHub Action to
your CI pipeline.

I. Docker

There are two options for getting a docker image:

1. Pulling an official image from Docker Hub

docker pull pilosus/pip-license-checker

Use specific version tag (it's matching version of the tool in the repo) or just latest.

2. Building a docker image yourself

bashCopy
git clone https://github.com/pilosus/pip-license-checker.git
cd pip-license-checker
docker build -t pilosus/pip-license-checker .

II. Compiling from source code

1. Install Leiningen

2. Get the source code

bashCopy
git clone https://github.com/pilosus/pip-license-checker.git
cd pip-license-checker

It's enough to start using the tool with lein. But you can
optionally compile a standalone jar-file too:

3. (Optional) Compile uberjar file

bashCopy
lein uberjar
cd target/uberjar
java -jar pip-license-checker-[version]-standalone.jar [args] [options]

III. GitHub Action for CI integration

If your project is hosted by GitHub, try the GitHub
Action based
on pip-license-checker.

Usage

Docker

bashCopy
docker run -it --rm pilosus/pip-license-checker \
  java -jar app.jar 'aiostream==0.4.3' 'pygit2' 'aiohttp>3.7.1'

In case of checking files (e.g. with --requirements or --external
tool's options) mount a host directory containing the files with
docker's -v option:

bashCopy
docker run -v `pwd`:/volume \
    -e GITHUB_TOKEN=your-gh-token \
    -it --rm pilosus/pip-license-checker \
    java -jar app.jar --exclude 'pylint.*' \
    --requirements '/volume/requirements.txt' \
    --external '/volume/licenses.csv' \
    --fail StrongCopyleft \
    --fails-only \
    --verbose

Command line tool

Examples below assume you are using lein tool. If you'd like to use
standalone jar file, just substitute lein run with java -jar pip-license-checker-[version]-standalone.jar.

bashCopy
### see usage message
lein run

### check a single package
lein run piny==0.6.0
lein run aiostream

### include pre-release and development versions
lein run --pre aiohttp

### scan all packages in requirements file
lein run --requirements resources/requirements.txt

aiohttp:3.7.2                       Apache Software License                                 Permissive
piny:0.6.0                          MIT License                                             Permissive
aiostream:0.4.3                     GPLv3                                                   StrongCopyleft
mo-collections:4.30.21121           Mozilla Public License 2.0 (MPL 2.0)                    WeakCopyleft
aiocache:0.11.1                     BSD 3-Clause "New" or "Revised" License                 Permissive
aiokafka:0.6.0                      Apache Software License                                 Permissive
aiopg:122.3.5                       Error                                                   Error
telegram-bot-framework:3.15.2       GNU Affero General Public License v3 or later (AGPLv3+) NetworkCopyleft
aio-throttle:1.6.2                  MIT License                                             Permissive
workflow-tools:0.6.0                Apache Software License                                 Permissive
Synx:0.0.3                          Other/Proprietary License                               Other

### scan packages matching regex pattern
### e.g. all lines except containing "aio.*" packages
lein run --requirements resources/requirements.txt --exclude 'aio.*'

piny:0.6                       MIT License                    Permissive
workflow-tools:0.5.0           Apache Software License        Permissive
Synx                           Other/Proprietary License      Other

Help

Run application with lein run or use --help option with standalone
jar for more details.

bashCopy
lein run

pip-license-checker - license compliance tool to identify dependencies license names and types.

Usage:
pip-license-checker [options]... [package]...

Description:
  package	List of Python package names in format `name[specifier][version]`

  -v, --verbose                            0                                       Verbosity level: error (-v), info (-vv), debug (-vvv)
  -r, --requirements REQUIREMENTS_FILE     []                                      Python pip requirement file name
  -x, --external FILE_NAME                 []                                      File containing package names and license names
      --external-format FILE_FORMAT        csv                                     External file format: csv, cocoapods, gradle
      --external-options OPTS_EDN_STRING   {:skip-header true, :skip-footer true}  String of options map in EDN format
      --report-format FORMAT               stdout                                  Report format: stdout, json, json-pretty, csv
      --formatter PRINTF_FMT               %-35s %-55s %-20s %-40s                 Printf-style formatter string for stdout report formatting
  -f, --fail LICENSE_TYPE                  #{}                                     Return non-zero exit code if license type is found
  -e, --exclude REGEX                                                              PCRE to exclude packages with matching names
      --exclude-license REGEX                                                      PCRE to exclude packages with matching license names
      --[no-]pre                           false                                   Include pre-release and development versions. By default, use only stable versions
      --[no-]totals                        false                                   Print totals for license types
      --[no-]with-totals                   nil                                     [deprecated '0.41.0'] Print totals for license types
      --[no-]totals-only                   false                                   Print only totals for license types
      --[no-]headers                       false                                   Print report headers
      --[no-]table-headers                 nil                                     [deprecated '0.41.0'] Print table headers
      --[no-]fails-only                    false                                   Print only packages of license types specified with --fail flags
      --[no-]parallel                      true                                    Run requests in parallel
      --[no-]exit                          true                                    Exit program, used for CLI mode
      --rate-limits REQUESTS/MILLISECONDS  {:requests 120, :millis 60000}          Rate limit requests to public APIs
      --github-token TOKEN                 nil                                     GitHub OAuth Token to increase rate-limits. Defaults to GITHUB_TOKEN env
  -h, --help                                                                       Print this help message

Examples:
pip-license-checker django
pip-license-checker aiohttp==3.7.2 piny==0.6.0 django
pip-license-checker --pre 'aiohttp<4'
pip-license-checker --totals --headers --requirements resources/requirements.txt
pip-license-checker --totals-only -r file1.txt -r file2.txt -r file3.txt
pip-license-checker -r resources/requirements.txt django aiohttp==3.7.1 --exclude 'aio.*'
pip-license-checker -r resources/requirements.txt --rate-limits 10/1000
pip-license-checker -r resources/requirements.github.txt --github-token your-token
pip-license-checker -x resources/external.csv --exclude-license '(?i).*(?:mit|bsd).*'
pip-license-checker -x resources/external.csv --external-options '{:skip-header false}'
pip-license-checker -x resources/external.cocoapods --external-format cocoapods'
pip-license-checker -x resources/external.edn --external-format edn --formatter '%-70s %-60s %-35s %-40s'
pip-license-checker -r resources/requirements.txt --report-format 'json-pretty' --totals --headers -vvv

License types

The following valid license types are available (to be used with --fail option):

• NetworkCopyleft (GNU Affero GPL and the like)
• StrongCopyleft (GNU GPL and the like)
• WeakCopyleft (file-based or module-based copyleft like MPL or EPL)
• Copyleft (includes all of above)
• Permissive (BSD-style licenses)
• Other (EULA, licenses not detected by the tool)
• Error (no license name found or provided)

External file formats and their options

The tool supports multiple file formats containing package names and
license name. External file format can be specified with the
--external-format option.

Options specific to the file format can be specified with the
--external-options as a string in EDN format.

csv

A CSV file generated by
license-checker or
any other third-party tool.

At least two columns need to be present in the file: package name and license name.

Default --external-options are the following:

{:skip-header true :package-column-index 0 :license-column-index 1}

• skip-header [boolean]: skip the first line in a CSV file because it's a header line
• package-column-index [integer]: index of the column with a package name (zero-based indexing)
• license-column-index [integer]: index of the column with a license name (zero-based indexing)

edn

An EDN file generated by
lein-licenses, a
Clojure's leiningen plugin for detecting
licenses for the project's dependencies.

Default --external-options are the following:

{:fully-qualified-names true}

• {:fully-qualified-names [boolean]}: if true use fully-qualified
  dependency names, e.g. org.clojars.vrs/pip-license-checker:0.30.0.
  Otherwise try to strip a Clojars's group or a Maven's groupId part,
  e.g. pip-license-checker:0.30.0. Default value is true.

cocoapods

A propery list (plist) file generated by CocoaPods Acknowledgements plugin.

See available options in the documentation.

gradle

A JSON file generated by Gradle License Plugin.

See available options in the documentation.

External file options

The following valid external file options are available (to be used
with --external-options option) for the external formats:

• csv: '{:skip-header [boolean]}' -- skip the first (header) line of the csv file or not.
• cocoapods: see the documentation.
• gradle: see the documentation

FAQ

Q1. Does the tool consider the Python package's version? What if a package changes its license over time?

The tool resolves the version for Python packages just pip package
manager does. It also checks the license only for the resolved version
of the package.

Q2. How do I check all Python dependencies for my project, both explicit and transitive ones?

pip-license-checker checks only explicitly defined dependencies,
without
transitive
ones. The easiest way to check all dependencies is to get them by
the pip as the list and then run the tool with that list:

bashCopy
pip freeze > requirements-all.txt
lein run -r requirements-all.txt

Q3. Does the tool consider PEP-508 extras and markers specified for requirements?

PEP508 indeed allows
specifying extra packages to be installed for the package as well as
markers describing the rules when the dependency should be used:

requests[security];python_version<"3.9"

The tool ignores both extras and markers. Use the recipe for the
Q2 if you need extras/markers to have an effect on the final list
of dependencies to be checked.

Disclaimer

pip-license-checker is provided on an "as-is" basis and makes no
warranties regarding any information provided through it, and
disclaims liability for damages resulting from using it. Using
pip-license-checker does not constitute legal advice nor does it
create an attorney-client relationship.

License

Copyright © 2020-2025 Vitaly Samigullin

This program and the accompanying materials are made available under the
terms of the Eclipse Public License 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0.

This Source Code may also be made available under the following Secondary
Licenses when the conditions for such availability set forth in the Eclipse
Public License, v. 2.0 are satisfied: GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or (at your
option) any later version, with the GNU Classpath Exception which is available
at https://www.gnu.org/software/classpath/license.html.

SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0