Installation

Note

LiberTEM can currently be used on Python >=3.9.3, 3.10, 3.11 and 3.12.

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

LiberTEM is available to install through pip:

# Within a venv:
(libertem-venv) $ pip install libertem

and conda (via conda-forge):

# Within a conda env:
(libertem) $ conda install -c conda-forge libertem

Creating an isolated Python environment

It is good practice to use a dedicated virtual environment for LiberTEM and its dependencies to avoid affecting other environments on your system. To achieve this you can use a virtualenv or a conda environment, according to preference.

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.9 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) $

Now the environment is ready to install LiberTEM using the pip command at the top of this page.

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.

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.11

Activate the environment with the following command:

$ 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 using the conda command at the top of this page.

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

Optional dependencies

LiberTEM is capable of using additional dependencies to extend or enhance its features.

CuPy

GPU support is based on CuPy. See the CuPy installation documentation for installation of a precompiled binary packages compatible with your GPU. This is the recommended method to install CuPy, though it is also possible to installs CuPy from source using:

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

though this requires a build chain and can be time-consuming.

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.

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

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

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-venv) $ 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.

Air-gapped installation

Many microscope control computers are not connected to the internet, which means that the usual installation methods don’t work. It is not straightforward to package a Python application into a self-contained executable or installer for Windows, see also #39. Furthermore, relocating Python environments, for example with conda-pack doesn’t always work reliably. In order to install LiberTEM on an air-gapped machine, you need a computer with the same operating system, architecture and Python version as a host system where you can prepare all required packages for the target system.

On the host

  • Create a folder where you collect all required files, for example wheels.

  • If necessary, download and install a recent version of Python supported by LiberTEM and compatible with your systems from https://www.python.org/downloads/. This installer works without internet access.

  • Start a new command shell and change into the folder for the required files.

  • Confirm that you are using the intended Python version: python --version

  • Download and build all required packages for LiberTEM: python -m pip wheel libertem You can add more packages and extras to this command as desired, for example Jupyter etc.

  • Your folder wheels should now contain all required Python packages.

  • Transfer the folder wheels and the Python installer to the target machine.

On the target

  • If necessary, install the same Python version as on the host.

  • Start a new command shell and confirm the Python version: python --version

  • Create a virtual environment in a folder of your choice: python -m venv libertem-venv

  • Activate the environment: On Windows cmd.exe libertem-venv\Scripts\activate.bat

  • Change to the directory with the Python packages.

  • Install the LiberTEM package and other top-level packages using the package folder instead of the online package index: pip install --find-links . --no-index libertem

Docker and Singularity

New in version 0.9.0.

A Docker image with a LiberTEM installation is available on the GitHub container registry. See Containers for more details.

AppImage

On Linux it is possible to install LiberTEM in a standalone form using the provided AppImage file. To do this download the AppImage file from our releases page on GitHub, mark it executable and run the AppImage. See also the official documentation.

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.

Integration and deployment