Configuration

Configuration can come from a YAML file passed with -c, or be set directly on a Config object when using the library. Command line flags override file values.

osslili -c osslili.yaml /path/to/project

from osslili import LicenseCopyrightDetector, Config
from osslili.utils.config_loader import ConfigLoader

config = ConfigLoader.load_from_file("osslili.yaml")
detector = LicenseCopyrightDetector(config)

Unknown keys are logged as warnings and ignored, so a typo will not silently change behaviour — run with -v to see them.

Example

# Matching
similarity_threshold: 0.97

# Traversal
max_recursion_depth: 4
max_extraction_depth: 3
thread_count: 4

# Scanning mode
license_files_only: true
strict_license_files: false
deep_scan: false

# Performance
skip_content_detection: false
skip_extensionless: false
skip_smart_read: false
max_file_size_kb: null
fast_mode: false

# Caching
cache_dir: ~/.cache/osslili

# Logging
verbose: false
debug: false

# What counts as a license file
license_filename_patterns:
  - "LICENSE*"
  - "LICENCE*"
  - "COPYING*"
  - "NOTICE*"
  - "*THIRD-PARTY*"

license_fuzzy_base_names:
  - license
  - licence
  - copying
  - copyright
  - notice

# Extra name-to-SPDX mappings, merged with the built-in aliases
custom_aliases:
  "My Company License": "LicenseRef-MyCompany"
  "Apache Software License": "Apache-2.0"

Options

Matching

Option	Default	Description
`similarity_threshold`	`0.97`	Minimum text similarity for a full-text match. Lowering it increases recall and false positives.

Traversal

Option	Default	Description
`max_recursion_depth`	`4`	Directory recursion limit. `-1` for unlimited.
`max_extraction_depth`	`3`	Nested archive extraction limit.
`thread_count`	`4`	Worker threads.

max_extraction_depth defaults to 3 on a bare Config, but the --max-extraction-depth flag defaults to 10 and always sets it. A library caller who wants the CLI’s behaviour has to set it explicitly.

Scanning mode

Option	Default	Description
`license_files_only`	`true`	Scan license files, metadata, and README only. Set `false` for a full source scan.
`strict_license_files`	`false`	With `license_files_only`, restrict further to license files alone — no metadata, no README.
`deep_scan`	`false`	Comprehensive scan of all source files. Set together with `license_files_only: false`.

These three combine into the modes described in Usage:

Mode	`license_files_only`	`strict_license_files`	`deep_scan`
Default	`true`	`false`	`false`
Strict	`true`	`true`	`false`
Deep	`false`	`false`	`true`

Performance

Option	Default	Description
`fast_mode`	`false`	Preset; enables the three skips below and caps file size at 1024 KB.
`skip_content_detection`	`false`	Trust file extensions instead of sniffing content.
`skip_extensionless`	`false`	Skip files with no extension unless they match a known license filename.
`skip_smart_read`	`false`	Read files whole rather than sampling their start and end.
`max_file_size_kb`	`None`	Skip files larger than this. `None` means no limit.

Caching

Option	Default	Description
`cache_dir`	`None`	Directory for cached scan results. `None` disables caching.

Caching is keyed on the scanned path. Enable it when scanning the same trees repeatedly; leave it off for one-shot scans.

There is no --cache-dir command line flag — set cache_dir in a config file, or assign it on a Config object.

License file recognition

Option	Default	Description
`license_filename_patterns`	see below	Glob patterns identifying license files. Replaces the built-in list when set.
`license_fuzzy_base_names`	`license`, `licence`, `copying`, `copyright`, `notice`	Base names matched fuzzily, catching misspellings and suffixed variants.

The built-in patterns are:

LICENSE*  LICENCE*  COPYING*  NOTICE*
MIT-LICENSE*  APACHE-LICENSE*  BSD-LICENSE*
UNLICENSE*  COPYRIGHT*  3rdpartylicenses.txt
*GPL*  *COPYLEFT*
*EULA*  *COMMERCIAL*  *AGREEMENT*  *BUNDLE*
*THIRD-PARTY*  *THIRD_PARTY*  LEGAL*

Setting license_filename_patterns replaces this list rather than adding to it. To extend it, start from the built-in patterns and append.

Files matching a third-party marker together with a notice token — THIRD_PARTY_NOTICES, 3rdparty-licenses.txt — are still scanned, but their findings are categorized as third-party rather than as the project’s own license.

Aliases

Option	Default	Description
`custom_aliases`	see below	Extra license-name-to-SPDX mappings. Merged with the built-ins, not replaced.

Built-in aliases cover the common informal names:

Apache 2, Apache 2.0, Apache License 2.0  ->  Apache-2.0
MIT License                               ->  MIT
BSD License                               ->  BSD-3-Clause
ISC License                               ->  ISC
GPLv2 -> GPL-2.0    GPLv3 -> GPL-3.0
LGPLv2 -> LGPL-2.0  LGPLv3 -> LGPL-3.0

For a license with no SPDX identifier, map it to a LicenseRef- identifier — those pass the SPDX validation that would otherwise reject an invented name.

Logging

Option	Default	Description
`verbose`	`false`	Verbose logging.
`debug`	`false`	Debug logging, including rejected detection candidates and why.

Environment variables

Variable	Description
`OSLILI_DEBUG`	Set to `1` to keep SSL and urllib3 warnings visible, which osslili otherwise suppresses on import.