Installation

Note

LiberTEM is currently working with Python 3.6 and Python 3.7. Support for Python 3.8 depends on a more current release of Dask.distributed we are not compatible with yet. See also #452, #482.

Note

Distinguish between installing a released version and installing the latest development version. Both installing from PyPi and installing from a git clone use pip, but they do fundamentally different things. pip install libertem downloads the latest release from PyPi.

Changing directory to a git clone and running pip install -e . installs from the local directory in editable mode. “Editable mode” means that the source directory is linked into the current Python environment rather than copied. That means changes in the source directory are immediately active in the Python environment.

Installing from a git clone in editable mode is the correct setup for development work and using the latest features in the development branch. Installing from PyPI is easier and preferred for production use and for new users.

Note

This documentation currently assumes that you are using LiberTEM on a single computer. If you want to run on a cluster, please let us know by either filing an issue or by asking on our Gitter channel.

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.

Using virtualenv

You can use virtualenv or venv if you have a system-wide Python 3.6 or 3.7 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.6 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) to indicate that the environment is active:

(libertem) $

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 Python 3.6 or 3.7 installation, you can create a conda environment for LiberTEM.

This section assumes that you have installed conda 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.7

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

$ source 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) $ pip install libertem

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

Installing from a git clone

If you want to follow the latest development, you should install LiberTEM from a git clone:

$ git clone https://github.com/LiberTEM/LiberTEM

Or, if you wish to contribute to LiberTEM, create a fork of the LiberTEM repository by following these steps:

  1. Log into your GitHub account.

  2. Go to the LiberTEM GitHub home page.

  3. Click on the fork button:

    _images/forking_button.png
  4. Clone your fork of LiberTEM from GitHub to your computer

$ git clone https://github.com/your-user-name/LiberTEM

For more information about forking a repository. For a beginner-friendly introduction to git and GitHub, consider going through the following resources:

Activate the Python environment (conda or virtualenv) and change to the newly created directory with the clone of the LiberTEM repository. Now you can start the LiberTEM installation. Please note the dot at the end, which indicates the current directory!

(libertem) $ pip install -e .

This should download the dependencies and install LiberTEM 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) $ pip install "libertem[torch]"

Or from git checkout:

(libertem) $ pip install -e .[torch]

CuPy

GPU support is based on CuPy.

(libertem) $ pip install "libertem[cupy]"

Or from git checkout:

(libertem) $ pip install -e .[cupy]

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

If you have installed from a git clone, you can easily update it to the current status. Open a command line in the base directory of the LiberTEM clone and update the source code with this command:

$ git pull

The installation with pip install -e has installed LiberTEM in “editable” mode. That means the changes pulled from git are active immediately. Only if the requirements for installed third-party packages have changed, you should re-run pip install -e . in order to install any missing packages.

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.

Windows

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

For installing from a git clone you require a suitable git client, for example GitHub Desktop, TortoiseGit, or git for windows. Clone the repository https://github.com/LiberTEM/LiberTEM in a folder of your choice.

From here on 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:

  • The command to activate a conda environment on Windows is

> conda activate libertem
  • 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

Jupyter

To use the Python API from within a Jupyter notebook, you can install Jupyter into your LiberTEM virtual environment.

(libertem) $ pip install jupyter

You can then run a local notebook from within the LiberTEM environment, which should open a browser window with Jupyter that uses your LiberTEM environment.

(libertem) $ jupyter notebook

JupyterHub

If you’d like to use the Python API from a LiberTEM virtual environment on a system that manages logins with JupyterHub, you can easily install a custom kernel definition for your LiberTEM environment.

First, you can launch a terminal on JupyterHub from the “New” drop-down menu in the file browser. Alternatively you can execute shell commands by prefixing them with “!” in a Python notebook.

In the terminal you can create and activate virtual environments and perform the LiberTEM installation as described above. Within the activated LiberTEM environment you additionally install ipykernel:

(libertem) $ pip install ipykernel

Now you can create a custom ipython kernel definition for your environment:

(libertem) $ python -m ipykernel install --user --name libertem --display-name "Python (libertem)"

After reloading the file browser window, a new Notebook option “Python (libertem)” should be available in the “New” drop-down menu. You can test it by creating a new notebook and running

In [1]: import libertem

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.