User Guide¶

terrarium [options] COMMAND [requirements files...]

See terrarium --help for a complete list of options and commands.

Creating a new environment¶

The following example will create a new virtual environment named env that includes the packages defined in requirements.txt

$ terrarium --target env install requirements.txt

Replacing an existing environment¶

The following example demonstrates how terrarium can be used to replace an existing activated virtual environment with a different set of packages.

$ terrarium --target env install requirements.txt
$ source env/bin/activate
$ terrarium install other_requirements.txt

Note

The environment that was replaced is renamed to env.bak, and can be restored using terrarium revert.

Note

After installing the other_requirements, it is not necessary to run deactivate or activate to begin using the new environment.

Saving and using environment archives¶

Terrarium provides options for archiving and compressing a freshly installed and built environment, either locally or remotely (via Amazon S3).

When these options are used, terrarium will first check if the environment has already been saved. In that case, terrarium will download the environment archive instead of downloading and building each individual package specified in the requirements files.

Storing terrarium environments locally¶

Storing terrarium environments locally (or on a shared network disk) can be achieved using the --storage-dir option.

$ terrarium --target env --storage-dir path/to/environments install requirements.txt

After building a fresh environment from the requirements in requirements.txt, terrarium will archive and compress the environment. Finally, the compressed version is then copied to the path specified by --storage-dir.

Storing terrarium environments on Cloud Storage Services (S3, GCS)¶

Terrarium also supports storing and retrieving archives stored on these storage services:

Amazon Web Service - S3

Google Cloud Platform - Google Cloud Storage

Amazon S3¶

The following options are only available if boto is installed.

--s3-bucket

--s3-access-key

--s3-secret-key

--s3-max-retries

Google Cloud Storage¶

The following options are only available if gcloud is installed.

--gcs-bucket

--gcs-client-email

--gcs-secret-key

--gcs-max-retries

Note

Each of the above options can be specified using environment variables, e.g. S3_BUCKET, GCS_BUCKET instead of being passed in as a parameter.

Tips¶

Using an alternative index server¶

If you’re using an index server other than PyPI (perhaps an index server with internal-only packages), then you need to be able to tell terrarium to use that index URL. Terrarium does not have the -i (--index-url) option that pip has, so how do you indicate the index URL? Well, you may recall that pip requirements files can also contain command-line options… So add a line like this to one of your requirements files:

--index-url http://internal-index-server.corp/index

You can add a line like the above to an existing requirements file that has a list of packages or you could add it to a separate requirements file and then add that to the terrarium command-line.

$ terrarium --target testenv install internal-index-server.txt requirements.txt