Offline Mode


Table of contents

OSV-Scanner now supports offline scanning as an experimental feature. Offline scanning checks your project against a local database instead of calling the API.

This feature is experimental and might change or be removed with only a minor version update.

Specify database location

Our offline features require the use of a local database, the location of which is determined through the use of the OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY environment variable.

The local database file structure is in this form:


Where {local_db_dir} can be set by the OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY environment variable.

If the OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY environment variable is not set, OSV-Scanner will attempt to look for the database in the following locations, in this order:

  1. The location returned by os.UserCacheDir
  2. The location returned by os.TempDir

The database can be downloaded manually or by using the --experimental-local-db flag.

Offline option

The offline database flag --experimental-offline causes OSV-Scanner to scan your project against a previously downloaded local database. OSV-Scanner will not download or update the local database, nor will it send any project or dependency information anywhere. When a local database is not present, you will get an error message. No network connection is required when using this flag.

osv-scanner --experimental-offline ./path/to/your/dir

Local database option

The local database flag --experimental-local-db causes OSV-Scanner to download or update your local database and then scan your project against it.

osv-scanner --experimental-local-db ./path/to/your/dir

Manual database download

Instead of using the --experimental-local-db flag to download the database, it is possible to manually download the database.

A downloadable copy of the OSV database is stored in a GCS bucket maintained by OSV: gs://osv-vulnerabilities

This bucket contains zip files containing all vulnerabilities for each ecosystem at: gs://osv-vulnerabilities/<ECOSYSTEM>/

E.g. for PyPI vulnerabilities:

gsutil cp gs://osv-vulnerabilities/PyPI/ .

You can also download over HTTP via .

A list of all current ecosystems is available at gs://osv-vulnerabilities/ecosystems.txt.

Set the location of your manually downloaded database by following the instructions here.


  1. Commit level scanning is not supported.