license-checker

You can define a custom output structure using the --customPath flag and a JSON configuration file.

• For CSV: Specifies the columns to include. The module_name column is always included as the first column.
• For JSON: Adds the specified items to the standard output.

Available items for custom formats:

• name, version, description, repository, publisher, email, url, licenses, licenseFile, licenseText, licenseModified.

You can also provide default values for these items in your custom format JSON file.

license-checker --customPath customFormatExample.json

To use license-checker to inspect the licenses of a project and its dependencies, install it globally via npm and run the command within your project directory.

# Install globally
npm install -g license-checker

# Run in your project folder
license-checker

Output displays a tree of dependencies, their repositories, and their licenses. An asterisk (*) next to a license name indicates the license was deduced from files like README or LICENSE rather than being explicitly stated in package.json.

You can use the CLI to automatically fail a build (exit with code 1) if certain license conditions are met.

• --failOn [list]: Fails if any license in the semicolon-separated list is found.
• --onlyAllow [list]: Fails if any license not in the semicolon-separated list is found.

Constraint: You cannot use --failOn and --onlyAllow at the same time.

The license checker follows a specific precedence logic to identify a package's license:

1. package.json: It first looks at the license or licenses field in the dependency's package.json.
2. README.md: If no license is found in package.json, it attempts to parse the README.md file.
3. File System Scan: If neither of the above works, it scans the package directory for files that match common license filenames (e.g., LICENSE, COPYING).

If a package is marked as private in its package.json, its license is reported as UNLICENSED.

The license-checker CLI tool scans your NPM dependencies to report their licenses. It supports various output formats (Tree, JSON, CSV, Markdown, Summary) and allows for strict license enforcement via exit codes.

Note on Delimiters: As of v17, when using --failOn or --onlyAllow, use semicolons (;) as delimiters instead of commas, as license names may contain commas.

The tool uses the debug module for internal logging. You can view debug output by setting the DEBUG environment variable to one of the following markers:

• license-checker:error: For error logs.
• license-checker:log: For non-error logs.
• license-checker*: To see all logs.

Example:

$ export DEBUG=license-checker*; license-checker

You can require license-checker in your application to programmatically retrieve package data.

Use checker.init(options, callback) where options can include a start path. The callback receives an error or the sorted package data as an Object.

var checker = require('license-checker');

checker.init({
    start: '/path/to/start/looking'
}, function(err, packages) {
    if (err) {
        //Handle error
    } else {
        //The sorted package data
        //as an Object
    }
});

The license-checker CLI provides several flags to filter, format, and validate licenses.

Note on Delimiters: As of v17.0.0, the --failOn, --onlyAllow, --packages, and --excludePackages arguments use semicolons (;) as delimiters instead of commas to avoid conflicts with license names containing commas.

The init function is the primary entry point for programmatically scanning dependencies for licenses. It performs a recursive scan of the dependency tree starting from a specified path and returns a structured object containing license information for each package.

Parameters

• options (Object): Configuration object (see Configuration Options).
• callback (Function): A callback function called with (err, data). data is an object where keys are package@version and values are module information objects.

Usage

const checker = require('license-checker');

checker.init({ start: './' }, (err, data) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(data);
});