.. image:: logo.png :width: 730 :alt: Geomstats logo

Geomstats is a Python package for computations, statistics, machine learning and deep learning on manifolds.

The package is organized into two main modules: geometry and learning. The module geometry implements differential geometry: manifolds, Lie groups, fiber bundles, shape spaces, information manifolds, Riemannian metrics, and more. The module learning implements statistics and learning algorithms for data on manifolds. Users can choose between backends: NumPy, Autograd or PyTorch.

.. list-table:: :header-rows: 0

- Code
- |PyPI version|\ |Downloads|\ |Zenodo|\
- Continuous Integration
- |Build Status|\ |python|\
- Code coverage (np, autograd, torch)
- |Coverage Status np|\ |Coverage Status autograd|\ |Coverage Status torch|
- Documentation
- |doc|\ |binder|\ |tutorial|\
- Community
- |contributions|\ |Slack|\ |Twitter|\

Keep in touch with the community by joining us on our slack workspace <https://join.slack.com/t/geomstats/shared_invite/zt-15t8k0q7r-Duxt6j6aA3rDOIms2Vd~RQ>__!

NEWS:

2025: Discover our shape module, and its paper Learning from landmarks, curves, surfaces, and shapes in Geomstats <https://arxiv.org/abs/2406.10437>_ by Luis Pereira, Alice Le Brigant, Adele Myers, Emmanuel Hartman, Amil Khan, Malik Tuerkoen, Trey Dold, Mengyang Gu, Pablo Suárez-Serrato, and Nina Miolane, published in the ACM Transactions of Mathematical Software.
2023: Discover our information_geometry module <https://github.com/geomstats/geomstats/tree/main/geomstats/information_geometry>_ , and its paper Parametric information geometry with the package Geomstats <https://dl.acm.org/doi/abs/10.1145/3627538>_ by Alice Le Brigant, Jules Deschamps, Antoine Collas, and Nina Miolane, published in the ACM Transactions of Mathematical Software.
2023: Discover our foundational paper Introduction to Riemannian Geometry and Geometric Statistics: From Basic Theory to Implementation with Geomstats <https://www.nowpublishers.com/article/Details/MAL-098>_ by Nicolas Guigui, Nina Miolane and Xavier Pennec, published in Foundations and Trends in Machine Learning.
2021-2022: The white papers summarizing the findings from our ICLR 2021 and 2022 challenges of computational differential geometry and topology are available here (2021) <https://arxiv.org/abs/2108.09810>__ and here (2022) <https://arxiv.org/abs/2206.09048>_.
To get an overview of geomstats, see our introductory video <https://www.youtube.com/watch?v=Ju-Wsd84uG0&list=PLYx7XA2nY5GejOB1lsvriFeMytD1-VS1B&index=3>__.
To understand how geomstats is built, check out these slides <https://drive.google.com/file/d/1YxeGeLXrJdVQLBJQ-SYPirQ7V_UisqUw/view?usp=sharing>__.
To get started with geomstats, see the examples <https://github.com/geomstats/geomstats/tree/main/examples>__ and notebooks <https://github.com/geomstats/geomstats/tree/main/notebooks>__ directories.
The documentation of geomstats can be found on the documentation website <https://geomstats.github.io/>__.
Interested in information geometry? Go to our information_geometry <https://github.com/geomstats/geomstats/tree/main/geomstats/information_geometry>_ module.
To follow the scientific literature on geometric statistics, follow our twitter-bot @geomstats <https://twitter.com/geomstats>__!

Citing Geomstats

If you find geomstats useful, please kindly cite:

Geomstats: A Python Package for Riemannian Geometry in Machine Learning (JMLR 2020) <http://jmlr.org/papers/v21/19-027.html>__
Introduction to Riemannian Geometry and Geometric Statistics: from Basic Theory to Implementation with Geomstats (FnT ML 2023) <https://www.nowpublishers.com/article/Details/MAL-098>__
Parametric information geometry with the package Geomstats (ACM TOMS 2023) <https://arxiv.org/abs/2211.11643>__
Learning from landmarks, curves, surfaces, and shapes in Geomstats (ACM TOMS 2025) <https://arxiv.org/abs/2406.10437>__

@article{JMLR:v21:19-027,
  author  = {Nina Miolane and Nicolas Guigui and Alice Le Brigant and Johan Mathe and Benjamin Hou and Yann Thanwerdas and Stefan Heyder and Olivier Peltre and Niklas Koep and Hadi Zaatiti and Hatem Hajri and Yann Cabanes and Thomas Gerald and Paul Chauchat and Christian Shewmake and Daniel Brooks and Bernhard Kainz and Claire Donnat and Susan Holmes and Xavier Pennec},
  title   = {Geomstats:  A Python Package for Riemannian Geometry in Machine Learning},
  journal = {Journal of Machine Learning Research},
  year    = {2020},
  volume  = {21},
  number  = {223},
  pages   = {1-9},
  url     = {http://jmlr.org/papers/v21/19-027.html}
}

@article{miolane2020introduction,
  title     = {Introduction to geometric learning in python with geomstats},
  author    = {Miolane, Nina and Guigui, Nicolas and Zaatiti, Hadi and Shewmake, Christian and Hajri, Hatem and Brooks, Daniel and Le Brigant, Alice and Mathe, Johan and Hou, Benjamin and Thanwerdas, Yann and others},
  journal   = {SciPy 2020-19th Python in Science Conference},
  pages     = {48--57},
  year      = {2020},
  url       = {https://proceedings.scipy.org/articles/Majora-342d178e-007.pdf}
}

@article{guigui2023introduction,
  author  = {Guigui, Nicolas and Miolane, Nina and Pennec, Xavier and others},
  title   = {Introduction to riemannian geometry and geometric statistics: from basic theory to implementation with geomstats},
  journal = {Foundations and Trends{\textregistered} in Machine Learning},
  volume  = {16},
  number  = {3},
  pages   = {329--493},
  year    = {2023},
  publisher = {Now Publishers, Inc.}
  url     = {https://www.nowpublishers.com/article/Details/MAL-098}

}

@article{le2023parametric,
  author  = {Le Brigant, Alice and Deschamps, Jules and Collas, Antoine and Miolane, Nina},
  title   = {Parametric information geometry with the package Geomstats},
  journal = {ACM Transactions on Mathematical Software},
  volume  = {49},
  number  = {4},
  pages   = {1--26},
  year    = {2023},
  publisher = {ACM New York, NY}

}

@article{pereira2025learning,
  title   = {Learning from landmarks, curves, surfaces, and shapes in Geomstats},
  author  = {Pereira, Lu{\'\i}s F and Brigant, Alice Le and Myers, Adele and Hartman, Emmanuel and Khan, Amil and Tuerkoen, Malik and Dold, Trey and Gu, Mengyang and Su{\'a}rez-Serrato, Pablo and Miolane, Nina},
  journal = {ACM Transactions on Mathematical Software},
  year    = {2025},
  publisher = {ACM New York, NY}

and Geomstats software version <https://doi.org/10.5281/zenodo.4624475>__ (citation automatically generated by Zenodo at the bottom right of this link).

We would sincerely appreciate citations to both the original research paper and the software version, to acknowledge authors who started the codebase and made the library possible, together with the crucial work of all contributors who are continuously implementing pivotal new geometries and important learning algorithms, as well as refactoring, testing and documenting the code to democratize geometric statistics and (deep) learning and foster reproducible research in this field.

Install geomstats via pip3

From a terminal (OS X & Linux), you can install geomstats and its requirements with pip3 as follows:

pip3 install geomstats

This method installs the latest version of geomstats that is uploaded on PyPi. Note that geomstats is only available with Python3.

Install geomstats via conda

From a terminal (OS X & Linux) or an Anaconda prompt (Windows), you can install geomstats and its requirements with conda as follows:

conda install -c conda-forge geomstats

This method installs the latest version of geomstats that is uploaded on conda-forge. Note that geomstats is only available with Python3.

Install geomstats via Git

From a terminal (OS X & Linux), you can install geomstats and its requirements via git as follows:

git clone https://github.com/geomstats/geomstats.git
cd geomstats
pip3 install .

This method installs the latest GitHub version of geomstats.

Note that this only installs the minimum requirements. To add the optional, development, continuous integration and documentation requirements, refer to the file pyproject.toml.

Install geomstats : Developers

Developers should git clone the main branch of this repository, together with the development requirements and the optional requirements to enable autograd and pytorch backends:

pip3 install geomstats[dev,opt]

Additionally, we recommend installing our pre-commit hook, to ensure that your code follows our Python style guidelines:

pre-commit install

Choose the backend

Geomstats can run seamlessly with numpy, autograd or pytorch. Note that autograd and pytorch and requirements are optional, as geomstats can be used with numpy only. By default, the numpy backend is used. The visualizations are only available with this backend.

To get the autograd and pytorch versions compatible with geomstats, install the optional requirements:

pip3 install geomstats[opt]

To install only the requirements for a given backend do:

pip3 install geomstats[<backend_name>]

You can choose your backend by setting the environment variable GEOMSTATS_BACKEND to numpy, autograd or pytorch, and importing the backend module. From the command line:

export GEOMSTATS_BACKEND=<backend_name>

and in the Python3 code:

import geomstats.backend as

Geomstats

Install / Use

README