Installation#

Step 1: (Optional) Set up a virtual environment.

We strongly recommend installing Espresso within a virtual environment. This ensures that Espresso can install the various modules that it needs without the risk of breaking anything else on your system. There are a number of tools that can facilitate this, including venv, virtualenv, conda and mamba.

Ensure you have python>=3.6. Then, you can create a new virtual environment by running the command

$ python -m venv <path-to-new-env>/<env-name>

where <path-to-new-env> is your prefered location for storing information about this environment, and <env-name> is your preferred name for the virtual environmment. For example,

$ python -m venv ~/my_envs/espresso

will create a virtual environment named espresso and store everything within a sub-directory of your home-space named my_envs.

To ‘activate’ or ‘switch on’ the virtual environment, run the command

$ source <path-to-new-env>/<env-name>/bin/activate

At this point you effectively have a ‘clean’ Python installation. You can now install and use Espresso, following the instructions at step 2. When you are finished, you can run the command

$ deactivate

and your system will return to its default state. If you want to use Espresso again, simply re-run the ‘activate’ step above; you do not need to repeat the installation process. Alternatively, you can remove Espresso and the virtual environment from your system by running

$ rm -rf <path-to-new-env>/<env-name>

You can create a new virtual environment (using Python version 3.10) by running the command

$ virtualenv <path-to-new-env>/<env-name> -p=3.10

where <path-to-new-env> is your prefered location for storing information about this environment, and <env-name> is your preferred name for the virtual environmment. For example,

$ virtualenv ~/my_envs/espresso -p=3.10

will create a virtual environment named espresso and store everything within a sub-directory of your home-space named my_envs.

To ‘activate’ or ‘switch on’ the virtual environment, run the command

$ source <path-to-new-env>/<env-name>/bin/activate

At this point you effectively have a ‘clean’ Python installation. You can now install and use Espresso, following the instructions at step 2. When you are finished, you can run the command

$ deactivate

and your system will return to its default state. If you want to use Espresso again, simply re-run the ‘activate’ step above; you do not need to repeat the installation process. Alternatively, you can remove Espresso and the virtual environment from your system by running

$ rm -rf <path-to-new-env>/<env-name>

You can create a new virtual environment (using Python version 3.10) by running the command

$ conda create -n <env-name> python=3.10

where <env-name> is your preferred name for the virtual environmment. For example,

$ conda create -n espresso python=3.10

will create a virtual environment named espresso.

To ‘activate’ or ‘switch on’ the virtual environment, run the command

$ conda activate <env-name>

At this point you effectively have a ‘clean’ Python installation. You can now install and use Espresso, following the instructions at step 2. When you are finished, you can run the command

$ conda deactivate

and your system will return to its default state. If you want to use Espresso again, simply re-run the ‘activate’ step above; you do not need to repeat the installation process. Alternatively, you can remove Espresso and the virtual environment from your system by running

$ conda env remove -n <env-name>

Step 2: Install Espresso

Espresso is available on PyPI, so for most users installation is as simple as:

$ pip install geo-espresso

You can build Espresso from source. You are most likely to want to do this if you want to work in ‘developer mode’, and make changes to Espresso’s source code.

$ git clone https://github.com/inlab-geo/espresso.git
$ cd espresso
$ pip install -e .

The -e flag ensures that the module is installed in editable mode; you can omit this if you do not intend to make any changes.

If all has gone well, you should now be able to successfully import espresso within your Python interpreter or script.