google/osv.dev: the database behind OSV, and the scanner you actually install

What problem osv.dev solves, and who is actually the audience

Vulnerability data has historically been split across vendor advisories, each with its own identifier scheme, its own affected-version syntax and its own idea of what a package is. OSV exists to put a single machine-readable format in front of that mess. The project describes itself as an open source vulnerability DB and triage service, and the entry point most people meet first is https://osv.dev, which the README says is a deployed instance of the web UI.

The audience is narrow and specific. It is engineers building dependency scanners, SBOM pipelines, or internal security tooling who need to ask one question: given a package name, an ecosystem and a version, is there a known advisory, and which versions are affected? The API is the product for that audience. The repository is the machinery behind the API, and the README is explicit that the scanner lives somewhere else entirely, in its own repository at github.com/google/osv-scanner. That split trips people up constantly. If you arrived here because you want to run a scan on a lockfile, this is the wrong repository.

How the repository is laid out, and what each directory actually does

The README carries a directory table, and it is the most useful page in the repository. The core Python library lives in osv/, described as used in basically all Python services, with ecosystem package versioning helpers under ecosystems/ and datastore model definitions in models.py. The Go side lives in go/, a module of shared libraries and commands including cmd/api, cmd/importer, cmd/worker, cmd/exporter, cmd/recoverer and cmd/relations.

The web service is split: gcp/website holds the backend of the osv.dev web interface with the frontend in frontend3, and blog posts in blog. Feed conversion is separate again, in vulnfeeds/, a Go module that the README describes as mostly the NVD CVE conversion, plus an Alpine feed converter at cmd/alpine and a Debian feed converter at tools/debian written in Python. Deployment is Terraform and Cloud Deploy config files under deployment/, with CI docker files in docker/.

Two details are worth flagging. First, gcp/functions is described in the README as the Cloud Function for publishing PyPI vulnerabilities, and the parenthetical says maintained, but not developed. That is a maintenance signal straight from the project, and anyone depending on PyPI advisory publication should read it carefully. Second, the repository is not self-contained: the README states you will need to check out submodules for many local building steps to work, and gives the command for it. A plain clone will not build everything.

Installing the library and making a first query through the API

The Python package is named osv in pyproject.toml, versioned 0.1.2 there, with a PyPI release of 0.1.1 noted in the repository's release list. It requires Python 3.13 or later, and its dependencies are Google Cloud oriented: google-cloud-ndb, google-cloud-logging, google-cloud-pubsub, google-cloud-storage, plus semver, packageurl-python, pygit2 and others. That dependency list is the honest signal about what this library is for. It is built to run inside OSV's own GCP services, not as a lightweight client you drop into a laptop script.

The repository's Makefile defines the install command as poetry install, and every other target runs through poetry run. So the local setup is:

poetry install

After that, the Makefile exposes targets for each test surface: lib-tests runs the core Python library tests through ./run_tests.sh, go-tests runs the Go services tests from the go directory, api-server-tests runs the Go API server integration tests through ./tools/apitester/run_tests.sh, and update-api-snapshots refreshes API query snapshots by setting UPDATE_SNAPS=true on the same script.

If what you actually want is to query the hosted service rather than run the stack, the README points at the API documentation under google.github.io/osv.dev/api/ and at the language bindings in bindings/, which the README notes are currently Go only. That is the practical first use for most readers: call the documented API, or generate a client from the bindings, rather than standing up the GCP deployment.

The data dump path, and why gs://osv-vulnerabilities is a different commitment

The README states that data dumps are available from a GCS bucket at gs://osv-vulnerabilities, with more detail in the documentation. This matters because it is a genuinely different integration from calling the API. With the API you get freshness and someone else's uptime. With the dump you get a bulk copy you can index yourself, which is what you want if you are building an offline scanner, a mirror, or an air-gapped pipeline.

The trade-off is operational. A dump has to be re-fetched, and the README does not describe a scheduling mechanism, an incremental delta format, or a change feed in the text available here. Anyone choosing the dump path is choosing to solve refresh themselves. For a dependency scanner that runs in CI once a day, the API is almost certainly the right call. For a product that needs sub-second lookups across millions of packages, the dump is the right call and the refresh job is your problem.

The same section of the README is also where the schema question belongs. The OSV format itself is documented separately, and the repository carries a proto/ directory and a build-osv-protos target in the Makefile that regenerates Python protobuf bindings from the OSV schema. If you are writing your own consumer, that schema is the contract you code against, not the datastore models in osv/models.py, which are internal.

Where osv.dev is the wrong tool, and what the honest limitations are

The first limitation is structural: this repository does not scan anything. The README routes scanning to osv-scanner, and the scanner's supported inputs (lockfiles, Debian Docker containers, SPDX and CycloneDX SBOMs, git repositories) are documented there, not here. Cloning google/osv.dev to get scanning behaviour will not work.

The second is the Google Cloud coupling. The deployment directory is Terraform and Cloud Deploy, the Python library pulls in four google-cloud packages, and the README describes the repository as containing all the code for running https://osv.dev on GCP. Self-hosting on another provider is not a documented path. If your constraint is that vulnerability data must stay inside your own network, the realistic option is the data dump plus your own query layer, not a fork of this deployment.

The third is the maintenance picture on individual components. The README marks gcp/functions as maintained, but not developed. The last push to the repository was on 2026-04-22, and the most recent release listed is v0.1.3 on the same date. That is recent enough that the project is not abandoned, but the release cadence is modest: v0.1.1 in September 2025, v0.1.2 later that month, then v0.1.3 in April 2026. The Python library is at 0.1.x. Treat this as infrastructure that changes slowly, and do not expect the Python package to track the hosted API's behaviour release for release.

Finally, the README's own note about third party tools is a limitation in disguise. It lists community integrations such as Dependency-Track, pip-audit, Renovate, Trivy and GUAC, then states plainly that these are community built and not supported or endorsed by the core OSV maintainers. If you adopt one of them, you are adopting two support relationships, not one.

Alternatives: osv-scanner, GitHub Advisory Database, and the community tools

The nearest alternative is osv-scanner, and the difference is one of layer rather than quality. osv-scanner is the Go command-line tool that walks your dependencies and queries the OSV API; google/osv.dev is the database and API it queries. They are complementary, and the README says so directly. If you want a scan in CI, osv-scanner is the thing to install; if you want to build the lookup into your own product, the API documented from this repository is the thing to call.

A second comparison is the GitHub Advisory Database, which many teams already consume through Dependabot. The practical difference is identifier coverage and format. OSV is designed as a single schema across ecosystems, with per-ecosystem versioning helpers in osv/ecosystems/, and the vulnfeeds module exists precisely to convert external feeds (NVD CVEs, Alpine, Debian) into that shape. A vendor-native advisory feed gives you that vendor's view; OSV's value proposition is aggregation under one schema, which is also its weakness, because aggregation quality depends on the converters in vulnfeeds/.

Among the community tools the README lists, Dependency-Track and GUAC are the ones that overlap most with an SBOM-centric workflow, and Trivy overlaps on container and filesystem scanning. The README's own framing is the useful one: consult the OpenSSF Concise Guide for Evaluating Open Source Software before adopting them, because the OSV maintainers explicitly disclaim support for that list.

Licence, upgrade cost and what a fork actually commits you to

The repository is Apache-2.0, and pyproject.toml declares the same identifier for the Python package. Apache-2.0 includes an explicit patent grant and requires that you preserve notices and state changes; it does not obligate you to publish your own modifications the way a copyleft licence would. This is not legal advice, and if you plan to redistribute a modified deployment, have counsel read the NOTICE and attribution requirements rather than treating a one-line licence field as the whole story.

The upgrade cost is the part worth thinking about before you fork. The Python library is pinned to requires-python >=3.13,<4.0, so a Python version bump is a hard gate on the library. The dev dependencies include a comment explaining that protobuf is held below 7.0.0 because the Vanir signatures worker uses v6 and cannot consume v7-compiled protos. That is a real, documented version constraint that will bite anyone who tries to float protobuf forward. The Makefile's lint target auto-detects changed files while lint-all covers everything, which suggests the project expects contributors to run the narrow version locally and the full version in CI.

If you fork for a self-hosted deployment, you inherit the Terraform, the Cloud Build yamls, the submodule checkout step, and the test scripts across five separate test surfaces. That is a substantial surface to keep green through upstream changes, and the release cadence suggests you will be rebasing against a slowly moving target rather than a fast one.

Editorial conclusion

Adopt the hosted osv.dev API or the data dumps if you need vulnerability lookups keyed by package version, and read the scanner repository separately if you want command-line scanning, because google/osv.dev does not contain it. Do not clone this repository expecting a self-hosted scanner; it is the GCP deployment of the database, the website backend, the indexer and the feed converters, and the README itself points to google/osv-scanner for scanning. Before committing, check the OSV schema documentation for the ecosystems you care about, confirm whether the PyPI Cloud Function under gcp/functions is still on your critical path given the README labels it maintained but not developed, and decide whether you want the API or the gs://osv-vulnerabilities dump, since those are different integration costs.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes