Skip to content

Installation#

Dependencies#

Required dependencies#

  • Python (3.11 or later)
  • numpy (2.0.0 or later)
  • matplotlib (3.9 or later)
  • imageio-ffmpeg — ships a static FFmpeg binary used for animation export to MP4 / MOV / AVI
  • hpc-utils (0.1.4 or later)

Note

Writing animations to mp4 / mov / avi needs an FFmpeg binary. imageio-ffmpeg bundles one, so export works out of the box; a system FFmpeg on your PATH is used in preference when present. GIF and WebP export use Pillow and need no FFmpeg.

Optional dependencies — the tiles extra#

The geospatial basemap features need three extra packages: the web-tile basemap helper (cleopatra.basemap.tiles.add_tiles), the reference-data layers (cleopatra.basemap.reference.add_relief for relief PNG decoding, and cleopatra.basemap.reference.add_features(..., crs=...) for reprojection), the orthographic globe presets in cleopatra.basemap.projection, and CRS reprojection on the geographic glyphs (GeoMixin.add_tiles / add_features / add_relief / add_reference_map). They are bundled in the cleopatra[tiles] extra (pip) / the cleopatra-tiles package (conda) and are otherwise not installed:

It is recommended to install cleopatra into a virtual environment so its requirements do not interfere with your system Python.

conda#

cleopatra is available in the conda-forge channel:

conda install -c conda-forge cleopatra

# with the optional web-tile basemap support
conda install -c conda-forge cleopatra-tiles

The conda packages are built from the cleopatra-feedstock; the cleopatra-tiles output simply pulls in cleopatra plus the four [tiles] dependencies.

pip#

pip install cleopatra

# with the optional web-tile basemap support (cleopatra.basemap.tiles.add_tiles)
pip install "cleopatra[tiles]"

From sources#

The sources for cleopatra are hosted on the GitHub repo.

Install the latest development version directly from GitHub:

pip install git+https://github.com/serapeum-org/cleopatra.git

Or clone and do an editable install for development:

git clone https://github.com/serapeum-org/cleopatra.git
cd cleopatra
pip install -e .

Check the installation#

To confirm the install succeeded, import the package and print its version:

python -c "import cleopatra; print(cleopatra.__version__)"

This should print the installed version without errors.

Documentation#