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 a conda-like environment manager, e.g. Miniforge and that your installation is working.
You can create a new environment to install LiberTEM with the following command:
$ conda create -n libertem python=3.12
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 --versionDownload and build all required packages for LiberTEM:
python -m pip wheel libertemYou can add more packages and extras to this command as desired, for example Jupyter etc.Your folder
wheelsshould now contain all required Python packages.Transfer the folder
wheelsand 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 --versionCreate a virtual environment in a folder of your choice:
python -m venv libertem-venvActivate the environment: On Windows cmd.exe
libertem-venv\Scripts\activate.batChange 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.