terrarium

Installation

Requirements

  • CPython 2.7
  • virtualenv (only the latest 2 versions are officially supported and tested)

Note

As Python 2.7 is no longer being maintained, terrarium’s support for 2.7 is officially deprecated and will be removed in a future version.

Install using pip

$ pip install terrarium

Upgrade using pip

$ pip install -U terrarium

Quick Start

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.

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

Development

Building the documentation locally

  1. Install tox

    $ pip install tox

  2. Use tox

    $ tox -e docs

  3. Load HTML documentation in a web browser of your choice:

    $ browser docs/_build/html/index.html

Running tests

  1. Install tox

    $ pip install tox

  2. Use tox

    $ tox

Getting involved

The terrarium project welcomes help in any of the following ways:

  • Making pull requests on github for code, tests and documentation.
  • Participating on open issues and pull requests, reviewing changes

Pull Request Checklist

To have the best chance at an immediate merge, your pull request should have:

  • A passing Travis-CI build. If it fails, check the console output for reasons why.
  • New unit tests for new features or bug fixes.
  • New documentation in docs for any new features. You do want people to know how to use your new stuff, right?

Release process

  1. Update CHANGELOG.
  2. Bump the version number in __init__.py on master.
  3. Tag the version.
  4. Generate source and wheel distributions: python setup.py sdist bdist_wheel
  5. Upload to PyPI: twine upload dist/*

Release Notes

1.2.0

  • Support virtualenv 16 and 15
  • Added wheel distribution to PyPI.
  • Improved packaging (setup.cfg) and tox configuration
  • Announced deprecation for Python 2.7

1.1.0

1.0.1

1.0.0

1.0.0-rc.6

1.0.0-rc.5

1.0.0-rc.4

1.0.0-rc.3

1.0.0-rc.2

1.0.0-rc.1