Skip to main content

Software Heritage storage manager

Project description


Abstraction layer over the archive, allowing to access all stored source code artifacts as well as their metadata.

See the documentation for more details.

Quick start


Python tests for this module include tests that cannot be run without a local Postgresql database, so you need the Postgresql server executable on your machine (no need to have a running Postgresql server). They also expect a cassandra server.

Debian-like host

$ sudo apt install libpq-dev postgresql-11 cassandra

Non Debian-like host

The tests expects the path to cassandra to either be unspecified, it is then looked up at /usr/sbin/cassandra, either specified through the environment variable SWH_CASSANDRA_BIN.

Optionally, you can avoid running the cassandra tests.

(swh) :~/swh-storage$ tox -- -m 'not cassandra'


It is strongly recommended to use a virtualenv. In the following, we consider you work in a virtualenv named swh. See the developer setup guide for a more details on how to setup a working environment.

You can install the package directly from pypi:

(swh) :~$ pip install

Or from sources:

(swh) :~$ git clone
(swh) :~$ cd swh-storage
(swh) :~/swh-storage$ pip install .

Then you can check it's properly installed:

(swh) :~$ swh storage --help
Usage: swh storage [OPTIONS] COMMAND [ARGS]...

  Software Heritage Storage tools.

  -h, --help  Show this message and exit.

  rpc-serve  Software Heritage Storage RPC server.


The best way of running Python tests for this module is to use tox.

(swh) :~$ pip install tox


From the sources directory, simply use tox:

(swh) :~/swh-storage$ tox
========= 315 passed, 6 skipped, 15 warnings in 40.86 seconds ==========
_______________________________ summary ________________________________
  flake8: commands succeeded
  py3: commands succeeded
  congratulations :)

Note: it is possible to set the JAVA_HOME environment variable to specify the version of the JVM to be used by Cassandra. For example, at the time of writing this, Cassandra does not support java 14, so one may want to use for example java 11:

(swh) :~/swh-storage$ export JAVA_HOME=/usr/lib/jvm/java-14-openjdk-amd64/bin/java
(swh) :~/swh-storage$ tox


The storage server can be locally started. It requires a configuration file and a running Postgresql database.

Sample configuration

A typical configuration storage.yml file is:

  cls: local
  db: "dbname=softwareheritage-dev user=<user> password=<pwd>"
    cls: pathslicing
    root: /tmp/swh-storage/
    slicing: 0:2/2:4/4:6

which means, this uses:

  • a local storage instance whose db connection is to softwareheritage-dev local instance,

  • the objstorage uses a local objstorage instance whose:

    • root path is /tmp/swh-storage,

    • slicing scheme is 0:2/2:4/4:6. This means that the identifier of the content (sha1) which will be stored on disk at first level with the first 2 hex characters, the second level with the next 2 hex characters and the third level with the next 2 hex characters. And finally the complete hash file holding the raw content. For example: 00062f8bd330715c4f819373653d97b3cd34394c will be stored at 00/06/2f/00062f8bd330715c4f819373653d97b3cd34394c

Note that the root path should exist on disk before starting the server.

Starting the storage server

If the python package has been properly installed (e.g. in a virtual env), you should be able to use the command:

(swh) :~/swh-storage$ swh storage rpc-serve storage.yml

This runs a local swh-storage api at 5002 port.

(swh) :~/swh-storage$ curl
<head><title>Software Heritage storage server</title></head>
<p>You have reached the
<a href="">Software Heritage</a>
storage server.<br />
See its
<a href="">documentation
and API</a> for more information</p>

And then what?

In your upper layer (loader-git, loader-svn, etc...), you can define a remote storage with this snippet of yaml configuration.

  cls: remote
  url: http://localhost:5002/

You could directly define a local storage with the following snippet:

  cls: local
  db: service=swh-dev
    cls: pathslicing
    root: /home/storage/swh-storage/
    slicing: 0:2/2:4/4:6

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for, version 0.21.0
Filename, size File type Python version Upload date Hashes
Filename, size (246.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size (279.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page