Installation

To run Sumatra you will need Python installed on your machine. If you are running Linux or Mac OS, you almost certainly already have it. If you don’t have Python, you can install it from python.org, or install one of the “value-added” distributions aimed at scientific users of Python, such as Python(x,y) or Anaconda.

We recommend installing Sumatra in a Python virtual environment created with conda or with the venv module.

Default installation

To install Sumatra with the most commonly used features, run the following:

$ pip install sumatra[default]

or if you’re on a Mac, using zsh:

$ pip install "sumatra[default]

This installs Sumatra with the web interface, remote record store access and support for the Git version control system.

Minimal installation

For a minimal installation of Sumatra, without Django or any version control support, run simply:

$ pip install sumatra

Installing Python bindings for your version control system

Sumatra currently supports Mercurial, Subversion and Git. If you are using Subversion, you will need to install the pysvn bindings, which cannot be installed with pip. To install bindings for Mercurial or Git, specify the appropriate option:

$ pip install sumatra[git,hg]

Other install options

A full list of install options is as follows:

  • web: enables the smtweb command (browser-based GUI) and the DjangoRecordStore

  • git: Git support

  • hg: Mercurial support

  • remote: enables the HttpRecordStore

  • postgres: allows use of PostgreSQL with the DjangoRecordStore

  • latex: for reproducible publications using LaTeX

  • sphinx: for reproducible publications using Sphinx

  • mpi: for launching distributed computations using MPI

  • docs: for building the Sumatra documentation

  • default: equivalent to “web,git,remote”

  • test: for running the test suite

  • dev: additional packages needed for developers of Sumatra

Command completion for bash

Sumatra comes with a limited bash completion facility. You can install it on your system by sourcing the file smt-completion.sh in your .bashrc or .profile. By default, Sumatra installs this script to the `bin directory of your virtual environment, or to /usr/bin, but moving it elsewhere (e.g., to ~/.bash_completion.d/) is recommended.