installation.rst

Installation

Pyresample can be installed from PyPI via pip or in a conda environment using the conda-forge channel. The below sections will show the possible ways to install Pyresample and what customizations can be made.

With pip

Pyresample is available from PyPI and can be installed with pip:

pip install pyresample

With conda

Pyresample can also be installed with conda or mamba via the conda-forge channel:

conda install -c conda-forge pyresample

From source

You can install Pyresample from a source tarball (or other source directory):

tar -zxvf pyresample-<version>.tar.gz
cd pyresample-<version>
pip install .

You could also install directly from github:

pip install git+https://github.com/pytroll/pyresample.git@main

Where main is the primary git branch. This branch name and the user account in the URL (pytroll above) can be customized to install in-development git branches.

For development

If you'd like to edit Pyresample and see the effects of the changes on your current environment, you can install it in "editable" mode:

pip install -e .

Note that Pyresample has some C extensions that must be recompiled if modified. This compilation only happens during installation/build time so the above command needs to be rerun to see the effects of changes to these extension modules.

Run tests

Testing pyresample requires all optional packages to be installed. Without all of these dependencies some tests may fail. To run tests from a local source directory:

pytest pyresample/test/

Or you can run it on an installed version of the package:

pytest --pyargs pyresample.test

If all the tests passes the functionality of all pyresample functions on the system has been verified.

Optional dependencies

Pyresample has a lot of functionality that may not be necessary for all users. These features only import their dependencies when used so it may not be obvious that you need them until after installation. These dependencies are not installed by default and must be installed separately.

In order to use the Pyresample plotting functionality cartopy and matplotlib must be installed. These packages are not a prerequisite for using any other pyresample functionality.

Additionally, for dask and xarray support these libraries must also be installed. Some utility functions may have additional, hopefully obvious, dependencies. For example, converting an object from the rasterio library requires rasterio to be installed.

Portions of Pyresample offer non-dask multiprocessing interfaces and may have additional dependencies to accomplish this. For example, when nprocs is available and specified with a value greater than 1, a special Proj_MP will be used and requires the KDTree class from the scipy package. Newer xarray/dask interfaces are recommended when possible.

Some of pyresamples functionality uses the KDTree object from the pykdtree package. This package benefits from being built with multi-threaded support via the OpenMP library, but this support is not always built-in by default. See the pykdtree README for build tips and suggestions. You may want to control the number of threads used by pykdtree with the OMP_NUM_THREADS environment variable.

Pyresample also uses the numexpr package for some minor bottleneck optimization if available.