License Finder Documentation

License Finder automatically detects supported languages by looking for specific package definition files in your project directory.

Key detection files include:

• Ruby: Gemfile (bundler)
• Node.js: package.json (npm)
• Python: requirements.txt (pip), Pipfile.lock (pipenv)
• Java: pom.xml (maven), build.gradle or build.gradle.kts (gradle)
• Go: go.mod (go mod), Gopkg.lock (dep), Godeps/Godeps.json (godep)
• Swift/iOS: Podfile (cocoapods), Cartfile (carthage), or workspace-state.json (SPM)
• Rust: Cargo.lock (cargo)
• PHP: composer.lock (composer)
• JavaScript: yarn.lock (yarn)

Note: For CocoaPods, you can target a specific target by setting the ACKNOWLEDGEMENTS_PATH environment variable.

Before running, ensure your dependencies are already installed (e.g., via bundle install or npm install).

To scan your project, run:

license_finder

If you installed via Bundler, use:

bundle exec license_finder

On the first run, it will list all packages. Subsequent runs will only report new or unapproved packages.

Useful Options:

• --quiet: Suppresses progressive output "dots".
• --debug: Provides detailed output about package discovery and license detection.
• --prepare or -p: Automatically runs the package manager's prepare command (e.g., npm install) before scanning.
• --prepare-no-fail: Runs the prepare step but continues even if it fails.

To support Conan, you must add the following to your conanfile.txt so license_finder can retrieve licenses:

[imports]
., license* -> ./licenses @ folder=True, ignore_case=True

When license_finder reports an unapproved dependency, you can approve it to stop it from appearing in future reports.

Approve a package by name:

$ license_finder approvals add <package_name>

Approve a specific version:

$ license_finder approvals add <package_name> --version=<version>

Approve with metadata (who and why):

$ license_finder approvals add <package_name> --who <name> --why "<reason>"

license_finder approvals add awesome_gpl_gem --who CTO --why "Go ahead"

To maintain consistent versions of all package managers, you can use the dlf script which runs commands inside a pre-provisioned Docker container. The container mounts your current directory at /scan.

Note: If your command contains &&, you must wrap the command in quotes.

Examples:

# Check a package manager version
$ dlf npm --version

# Run help
$ dlf license_finder --help

# Run a combined command
$ dlf "bundle install && license_finder"

To support SBT, you must have sbt-license-report installed. By default, it reports on compile and test dependencies. To change this, update your build.sbt:

licenseConfigurations := Set("compile", "provided")

Instead of approving packages one-by-one, you can define blanket policies for entire licenses. For example, to permit all packages using the MIT license:

$ license_finder permitted_licenses add MIT

Any current or future packages with the permitted license will be excluded from the output. You can also use --who and --why when adding permitted licenses.

You can install License Finder using several methods depending on your workflow:

As a command line tool (Recommended)

Install it directly via RubyGems:

$ gem install license_finder

As a pre-commit hook

Add the following to your .pre-commit-config.yaml to run license checks automatically before commits:

repos:
  - repo: https://github.com/pivotal/LicenseFinder
    rev: v7.1.0 # Use the latest tag
    hooks:
      - id: license-finder

In a Ruby project via Bundler

Add it to your Gemfile in the development group:

gem 'license_finder', :group => :development

Requirements: Running License Finder directly requires Ruby 2.6.0 or greater.

License Finder requires the license-gradle-plugin to be installed in your project. By default, it reports on runtime dependencies. To report on a different configuration (like compile for Android), add the following to your build.gradle:

// Must come *after* applying the license-gradle-plugin
downloadLicenses {
  dependencyConfiguration "compile"
}

License Finder identifies Conan projects by looking for the following files in the project root:

• conanfile.txt
• conanfile.py

The Conda adapter identifies dependencies by looking for environment definition files in the project root. It supports the following files:

• environment.yaml
• environment.yml

License Finder uses the name field defined within these YAML files to identify the target Conda environment.