Skip to main content
SCANOSS-PY provides a simple, easy-to-consume library for interacting with SCANOSS APIs and engines.

​
Prerequisites

Before you begin, make sure you have:

​
Installation

​
Standard Installation

Install SCANOSS-PY from PyPI: 
# Install from PyPI
pip3 install scanoss

# Upgrade existing installation
pip3 install --upgrade scanoss

​
Fast Winnowing

Provides 15x performance improvement in fingerprinting. 
# Install with fast winnowing support
pip3 install scanoss[fast_winnowing]

# Or install separately
pip3 install scanoss_winnowing

​
Dependency Scanning

To enable dependency detection from package manifests and lockfiles, install scancode-toolkit: 
pip install scancode-toolkit
scancode-toolkit is only required if you want to use the -D or --dependencies flag for scanning declared dependencies. Standard file and snippet scanning does not require this dependency.

​
Installation on Externally Managed Environments

Modern Linux distributions (Ubuntu 23.04+, Fedora 38+, Debian 11+). 
# Install pipx
sudo apt install pipx
pipx ensurepath

# Install scanoss-py
pipx install scanoss

# Upgrade existing installation
pipx upgrade scanoss

# Install scanoss-py with fast winnowing support
pipx install scanoss[fast_winnowing]

# Instal scancode-toolkit to scan for scanning declared dependencies
pipx install scancode-toolkit

​
Docker Installation

# Pull the latest Docker image
docker pull ghcr.io/scanoss/scanoss-py:latest

# Run the Python CLI
docker run -it ghcr.io/scanoss/scanoss-py

# Scan current folder
docker run -it -v "$(pwd)":"/scanoss" ghcr.io/scanoss/scanoss-py scan .

# Scan with output file
docker run -it -v "$(pwd)":"/scanoss" ghcr.io/scanoss/scanoss-py scan -o results.json .

# Scan with dependencies
docker run -it -v "$(pwd)":"/scanoss" ghcr.io/scanoss/scanoss-py scan -D -o results.json .

# Redirect output to file
docker run -i -v "$(pwd)":"/scanoss" ghcr.io/scanoss/scanoss-py scan . > output.json

# Use scancode for license and dependency detection
docker run -it -v "$(pwd)":"/scanoss" --entrypoint scancode ghcr.io/scanoss/scanoss-py --json-pp /scanoss/results.json -l -p .

​
Configuration

​
API Access Setup

While SCANOSS works without an API key, the free tier has usage limitations. To avoid hitting these limits, configure your API key before scanning. Set API Key via Environment Variables: 
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export SCANOSS_API_KEY=your_api_key_here' >> ~/.bashrc
source ~/.bashrc
scanoss-py automatically detects the SCANOSS_API_KEY environment variable when set. You can also pass the API key directly with --key $SCANOSS_API_KEY when running the tool.

​
Getting Started

​
Basic Scanning

# Scan a directory
scanoss-py scan -o results.json /path/to/folder

# Scan with dependency detection
scanoss-py scan -D -o results.json /path/to/folder

# Scan with specific settings
scanoss-py scan -D --settings scanoss.json -o results.json /path/to/folder

​
Viewing results

# View raw results
cat results.json

# Inspect undeclared components
scanoss-py inspect undeclared -i results.json

# Check for copyleft licenses
scanoss-py inspect copyleft -i results.json

# Generate component summary
scanoss-py inspect component-summary -i results.json --output components.json