> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCANOSS-PY

> A comprehensive Python library and CLI tool for Software Composition Analysis. CLI tool for Software Composition Analysis. Scan your code for open source components, dependencies and license compliance.

[SCANOSS-PY](https://github.com/scanoss/scanoss.py) provides a simple, easy-to-consume library for interacting with SCANOSS APIs and engines.

## Prerequisites

Before you begin, make sure you have:

* [Python 3.9 or higher](https://www.python.org/)

## Installation

### Standard Installation

Install SCANOSS-PY from [PyPI](https://pypi.org/project/scanoss/):

```bash theme={null}
# Install from PyPI
pip3 install scanoss

# Upgrade existing installation
pip3 install --upgrade scanoss
```

### Fast Winnowing

Provides 15x performance improvement in fingerprinting.

```bash theme={null}
# 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`:

```bash theme={null}
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+).

```bash theme={null}
# 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

```bash theme={null}
# 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:**

```bash theme={null}
# 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

```bash theme={null}
# 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
```

### Scanning with Snippet Tuning

SCANOSS-PY exposes snippet tuning parameters via CLI flags that let you control match sensitivity directly from the command line.

**Reduce False Positives:**

```bash theme={null}
# Require higher confidence matches
scanoss-py scan \
  --min-snippet-hits 5 \
  --min-snippet-lines 3 \
  --ranking-threshold=5 \
  -o results.json /path/to/folder
```

#### How Snippet Tuning Works

When you use these settings, `scanoss-py`:

1. Reads your `scanoss.json` (if present)
2. Reads CLI arguments (used as fallback only)
3. Merges both sources — `scanoss.json` takes precedence over CLI
4. Encodes the merged settings
5. Sends to the SCANOSS API
6. Server applies tuning during the scan

For more details on configuring these parameters in `scanoss.json`, see the <a href="/en/latest/poc/license-dataset/snippet-detection/snippet-tuning-guide" target="_blank">SCANOSS Settings documentation</a>.

### Viewing results

```bash theme={null}
# 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
```