> ## 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. # Migrating to v3 > Who is affected by the move from the SCANOSS v2 API to v3, what changes for each kind of customer, what keeps working on v2, and which guide to read next. This guide is for customers who use the SCANOSS v2 API today: `scanoss-py` against `/scan/direct`, the SCANOSS integrations built on it, or a self-hosted SCANOSS deployment. It explains what changes in v3, who needs to act, and where to go next. We recommend v3 for new work and for any pipeline you are about to change. v2 keeps working for now. There is no date by which you must move. ## What v3 is v3 is the current SCANOSS API. Every endpoint lives under `/v3`, on one service: scanning, decoration (licences, vulnerabilities, cryptography, dependencies, geoprovenance, copyright, components), and file contents. A scan is a chunked upload of fingerprints followed by polling for the result, so large projects don't need one long request. The client for v3 is [scanoss-cli](https://docs.scanoss.com/en/latest/cli/scanoss-go/installation.md), a Go command-line tool that replaces `scanoss-py` for scanning in your own pipelines. v2 and v3 are not interchangeable. `scanoss-cli` only speaks v3, so it can't talk to a v2 server or to OSSKB.org. `scanoss-py` speaks v2, so it can't talk to a v3 server. ## Why move to v3 ### Results that understand your project v2 identifies each file on its own. v3 looks at the whole project first: it counts which components the files share, ranks them across the project, and only then picks the best match for each file. Short or generic files that a v2 scan attributes to whichever repository copied them get the right component, because the rest of the project points to it. In our tests on CPython 3.14, scanning files one at a time put the correct component first in 80% of the cases. With project context, it came first in every file that matched: 3,340 out of 3,340. The scan also runs in passes. Every file is matched as a whole first, and snippet matching runs only on the files that found no full-file match. This keeps the snippet pass focused on the code that needs it. ### A confidence grade on every match Each match in a v3 result says how sure SCANOSS is: `HIGH`, `MEDIUM`, or `LOW`, along with its match percentage. The grade takes into account how much of your project shares the component, whether the file sits at the same path as in the component, the size of a snippet, and whether the match looks like a vendored copy or a fork. You can review `LOW` matches first and trust `HIGH` ones. We validated the grades on about 300 open-source projects. More than 99% of the correct matches were graded `HIGH`, and fewer than 1 in 10,000 correct matches were graded `LOW`. You also choose how many candidate components each match reports, from one up to all of them, with `--max-components`. ### Large scans that finish v2 sends fingerprints in many small synchronous requests, and a long scan can hit a timeout. v3 uploads the fingerprints in blocks, queues the scan on the server, and lets the client poll for the result. If the connection drops while you wait, `scanoss-cli results ` fetches the result of the same scan instead of starting again. ### One API for scanning and decoration Scanning and every decoration service live under `/v3` on one service, with one API key. Most lookups take a batch of components in one request (licences, vulnerabilities, cryptography, dependencies, and more) and report a status for each item, so one bad PURL doesn't fail the rest. Newer capabilities, such as cryptography reachability, exist only in v3. See the [API overview](https://docs.scanoss.com/en/latest/developer-tools/api-overview.md). ### A simpler client `scanoss-cli` is a single binary with no Python runtime to install or keep up to date. It builds CycloneDX 1.7 and SPDX 2.3 SBOMs locally from the scan result, applies your `scanoss.json` BOM rules, and can enrich an existing SBOM. See [scanoss-cli](https://docs.scanoss.com/en/latest/cli/scanoss-go/installation.md). ### A smaller knowledge base for self-hosted deployments The crc64 knowledge base that v3 uses takes about 7.5 TB, against 25 to 27 TB for the v2 KB. Our own v3 scan nodes run on 64 GB of RAM, half of what we recommend for a v2 deployment. A self-hosted v3 deployment also serves the full set of decoration APIs from your own infrastructure. See [Hardware requirements](https://docs.scanoss.com/en/latest/installation/on-prem/deployment-guide/hardware-requirements.md). ## Who is affected | You are | What changes | Read | | - | - | - | | A **SaaS user running `scanoss-py` by hand** against `api.scanoss.com` | You install `scanoss-cli`, keep your API key, and learn new command names and a new output format. | [From scanoss-py to scanoss-cli](https://docs.scanoss.com/en/latest/developer-tools/migrating/from-scanoss-py.md) | | A **CI pipeline that runs `scanoss-py`** directly, or from the `ghcr.io/scanoss/scanoss-py` image | You swap the image or binary, rename environment variables, and rewrite any step that parses the JSON output. | [From scanoss-py to scanoss-cli](https://docs.scanoss.com/en/latest/developer-tools/migrating/from-scanoss-py.md#migrate-a-ci-pipeline) | | A **user of a SCANOSS integration**: the GitHub Action, GitLab, Azure DevOps, Jenkins, pre-commit hooks, SBOM Workbench, Code Compare, or the `scanoss.js` SDK | Nothing, unless you decide to move. These stay on v2. See [Integrations](#integrations). | [Integrations](#integrations) | | A **self-hosted (on-premises) customer** | v3 needs a new knowledge base line (crc64), a new engine and LDB, and a new API service. You run it next to your v2 deployment and move clients over. | [Self-hosted: v2 to v3](https://docs.scanoss.com/en/latest/developer-tools/migrating/self-hosted.md) | | A user of the **free OSSKB.org** service | Nothing. OSSKB.org stays on v2 and works with `scanoss-py`. `scanoss-cli` can't use it. | — | ## What keeps working on v2 v2 keeps working for now. In particular: * `scanoss-py` and every tool built on it keep scanning against `api.scanoss.com` and OSSKB.org. * Self-hosted v2 deployments (the `scanoss-go-api` service, engine 5.x, LDB 4.x) keep working with the knowledge base you have today. * Your `scanoss.json` files keep working with `scanoss-py`. `scanoss-cli` reads the same file, with the differences listed in [Settings file](https://docs.scanoss.com/en/latest/developer-tools/migrating/from-scanoss-py.md#settings-file-scanoss-json). Because nothing is switched off, you can move one pipeline at a time and compare the results before you rely on them. ## Integrations These integrations run `scanoss-py` or call the v2 API, and they will stay on v2. SCANOSS won't move them to v3: * the SCANOSS code-scan GitHub Action (`scanoss/gha-code-scan`) * the GitLab, Azure DevOps, and Jenkins integrations * the SCANOSS pre-commit hooks * SBOM Workbench * Code Compare (scanoss.cc) * the `scanoss.js` SDK If you use one of them, you have three options: 1. **Keep it.** It keeps working on v2. 2. **Move to [Earnie](https://docs.scanoss.com/en/latest/earnie/introduction.md).** Earnie replaces the GitHub Action, the pre-commit hook, Code Compare, and policy checks with one platform. See [Migrating from SCANOSS Tools](https://docs.scanoss.com/en/latest/earnie/migrating/from-scanoss-tools.md). 3. **Build the same step with `scanoss-cli` and a Recipe.** Each Recipe is a plain shell script that runs in any CI system or Git hook: | You used | Recipe | | - | - | | The GitHub Action, or a CI plugin, on pull requests | [Scan every pull request in CI](https://docs.scanoss.com/en/latest/developer-tools/recipes/scan-pull-requests.md) | | Copyleft or policy checks | [Licence and vulnerability gate](https://docs.scanoss.com/en/latest/developer-tools/recipes/licence-and-vulnerability-gate.md) | | Identifications in Code Compare or `scanoss.json` | [Approve components with scanoss.json](https://docs.scanoss.com/en/latest/developer-tools/recipes/approve-components-bom-rules.md) | | The pre-commit hook | [Local pre-commit check](https://docs.scanoss.com/en/latest/developer-tools/recipes/pre-commit-check.md) | | `scanoss-py convert` to publish an SBOM | [Generate an SBOM for each release](https://docs.scanoss.com/en/latest/developer-tools/recipes/release-sbom.md) | | Scanning without sending source code | [Fingerprint-only scanning](https://docs.scanoss.com/en/latest/developer-tools/recipes/fingerprint-only-scanning.md) | ## Before you start Check these before you move anything: * **You have an API key.** `scanoss-cli` uses `https://api.scanoss.com` by default, and that endpoint requires a key. `scanoss-py` fell back to the free OSSKB.org service when you gave it no key. `scanoss-cli` doesn't. See [API keys and authentication](https://docs.scanoss.com/en/latest/developer-tools/authentication.md). * **You know which scripts read the scan output.** `scanoss-cli` writes a different JSON format. Anything that parses `scanoss-py` results (`jq` filters, report generators, uploads) needs rewriting. See [Output formats](https://docs.scanoss.com/en/latest/developer-tools/migrating/from-scanoss-py.md#output-formats). * **You know which `scanoss-py` commands you rely on.** Some have no `scanoss-cli` equivalent, for example `inspect` and `container-scan`. See [What has no equivalent](https://docs.scanoss.com/en/latest/developer-tools/migrating/from-scanoss-py.md#what-has-no-equivalent). * **You have a baseline.** Save a recent `scanoss-py` result for each project you move, so you can compare it with the first `scanoss-cli` result. Some defaults changed, and they can change what matches. * **Self-hosted only: you can run a second deployment.** v3 can't share a host with your v2 engine and LDB. Plan a separate host or container for v3. See [Self-hosted: v2 to v3](https://docs.scanoss.com/en/latest/developer-tools/migrating/self-hosted.md). ## Next steps > [card] [From scanoss-py to scanoss-cli](https://docs.scanoss.com/en/latest/developer-tools/migrating/from-scanoss-py.md) > > Commands, flags, environment variables, output, and CI pipelines. > [card] [Self-hosted: v2 to v3](https://docs.scanoss.com/en/latest/developer-tools/migrating/self-hosted.md) > > The crc64 knowledge base, engine 6, LDB 5, and the v3 API service. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.