Installation

Note

LiberTEM can currently be used on Python 3.7, 3.8, >=3.9.3 and 3.10.

If you would like to install the latest development version, please also see Installing from a git clone.

The short version

$ virtualenv -p python3 ~/libertem-venv/
$ source ~/libertem-venv/bin/activate
(libertem-venv) $ python -m pip install "libertem[torch]"

# optional for GPU support
# See also https://docs.cupy.dev/en/stable/install.html
(libertem-venv) $ python -m pip install cupy

For details, please read on!

Linux and Mac OS X

AppImage

On Linux, the easiest method is to use the provided AppImage. Just download the AppImage file from our releases page on GitHub, mark it executable and run the AppImage. See also the official documentation. Continue by reading the GUI usage.

Creating an isolated Python environment

To provide an isolated environment for LiberTEM and its dependencies, you can use virtualenvs or conda environments. This is important if you want to use different Python applications that may have conflicting dependencies, and it allows to quickly re-create an environment in case things go sideways.

Using virtualenv

You can use virtualenv or venv if you have a system-wide compatible Python installation. For Mac OS X, using conda is recommended.

To create a new virtualenv for LiberTEM, you can use the following command:

$ virtualenv -p python3 ~/libertem-venv/

If multiple Python versions are installed, replace python3 with python3.7 or a later version.

Replace ~/libertem-venv/ with any path where you would like to create the venv. You can then activate the virtualenv with

$ source ~/libertem-venv/bin/activate

Afterwards, your shell prompt should be prefixed with (libertem-venv) to indicate that the environment is active:

(libertem-venv) $

For more information about virtualenv, for example if you are using a shell without source, please refer to the virtualenv documentation. If you are often working with virtualenvs, using a convenience wrapper like virtualenvwrapper is recommended.

Continue by installing from PyPI.

Using conda

If you are already using conda, or if you don’t have a system-wide compatible Python installation, you can create a conda environment for LiberTEM.

This section assumes that you have installed anaconda or miniconda and that your installation is working.

You can create a new conda environment to install LiberTEM with the following command:

$ conda create -n libertem python=3.9

To install or later run LiberTEM, activate the environment with the following command (see also Windows if applicable):

$ conda activate libertem

Afterwards, your shell prompt should be prefixed with (libertem) to indicate that the environment is active:

(libertem) $

Now the environment is ready to install LiberTEM.

For more information about conda, see their documentation about creating and managing environments.

Installing from PyPI

To install the latest release version, you can use pip. Activate the Python environment (conda or virtualenv) and install using:

(libertem) $ python -m pip install libertem

This should install LiberTEM and its dependencies in the environment. Please continue by reading the GUI usage.

PyTorch

LiberTEM can use PyTorch for processing if it is available. Otherwise it uses NumPy as a fallback. We’ve experienced up to 2x speed-ups with PyTorch compared to a default NumPy installation. For that reason we recommend installing PyTorch. We currently use PyTorch only on the CPU. Contributions to use GPUs as well are very welcome!

You can let pip install PyTorch automatically by using the torch variant, for example from PyPI:

(libertem) $ python -m pip install "libertem[torch]"

CuPy

GPU support is based on CuPy. See https://docs.cupy.dev/en/stable/install.html#installing-cupy for installation of precompiled binary packages (recommended). python -m pip install "libertem[cupy]" installs CuPy from source, which requires a build chain and can be time-consuming.

New in version 0.6.0.

Other extra packages

Changed in version 0.4.0: A number of LiberTEM applications are being spun out as sub-packages that can be installed separately. See Package overview for an overview.

The full grid matching routines in libertem.analysis.fullmatch depend on HDBSCAN. This is an optional dependency because of installation issues on some platforms.

Updating

When installed from PyPI via pip, you can update like this:

(libertem) $ python -m pip install -U libertem

This should install a new version of LiberTEM and update all requirements that have changed.

After updating the installation, you can run the updated version by restarting the libertem-server and afterwards reloading all browser windows that are running the LiberTEM GUI. In other environments, like Jupyter notebooks, you need to restart the Python interpreter to make sure the new version is used, for example by restarting the ipython kernel.

Windows

The recommended method to install LiberTEM on Windows is based on Miniconda 64 bit with a compatible Python version. This installs a Python distribution.

The installation and running of LiberTEM on Windows with the Anaconda Prompt is very similar to Using conda on Linux or Mac OS X.

Differences:

You might have to install pip into your local LiberTEM conda environment to make sure that pip install installs packages into your local environment and not into the global Anaconda base environment. This helps to avoid permission issues and interference between environments.

(libertem) > conda install pip

Docker and Singularity

New in version 0.9.0.

A Docker image with a LiberTEM installation is available on Docker hub. See Containers for more details.

Troubleshooting

If you are having trouble with the installation, please let us know by either filing an issue or by asking on our Gitter channel.