gsd binaries are available in the glotzerlab-software Docker/Singularity images and in packages on conda-forge and PyPI. You can also compile gsd from source, embed gsd.c in your code, or read gsd files with a pure Python reader


Conda package#

gsd is available on conda-forge on the linux-64, linux-aarch64, linux-ppc64le, osx-64, osx-arm64 and win-64 platforms. To install, download and install miniforge or miniconda Then install gsd from the conda-forge channel:

$ conda install -c conda-forge gsd

Singularity / Docker images#

See the glotzerlab-software documentation for instructions to install and use the containers.


Use pip to install gsd binaries:

$ python3 -m pip install gsd

Compile from source#

To build the gsd Python package from source:

  1. Install prerequisites:

    $ <package-manager> install cmake cython git numpy python pytest
  2. Obtain the source:

    $ git clone
  3. Install with setuptools:

    $ python3 -m pip install -e gsd

    OR Build with CMake for development:

    $ cmake -B build/gsd -S gsd
    $ cmake --build build/gsd

To run the tests (optional):

  1. Run tests:

    $ pytest --pyargs gsd

To build the documentation from source (optional):

  1. Install prerequisites:

    $ <package-manager> install breathe doxygen sphinx furo ipython
  2. Build the documentation:

    $ cd gsd && doxygen && cd ..
    $ sphinx-build -b html gsd/doc build/gsd-documentation

The sections below provide details on each of these steps.

Install prerequisites#

gsd requires a number of tools and libraries to build.


This documentation is generic. Replace <package-manager> with your package or module manager. You may need to adjust package names and/or install additional packages, such as -dev packages that provide headers needed to build gsd.


Create or use an existing virtual environment, one place where you can install dependencies and gsd:

$ python3 -m venv gsd-venv

You will need to activate your environment before installing or configuring gsd:

$ source gsd-venv/bin/activate

General requirements:

  • C compiler (tested with gcc 9-12, clang 10-14, visual studio 2019-2022)

  • Python >= 3.8

  • numpy >= 1.17.3

  • Cython >= 0.22

To build the documentation:

  • breathe

  • Doxygen

  • Sphinx

  • IPython

  • furo

  • an internet connection

To execute unit tests:

  • pytest >= 3.9.0

Obtain the source#

Clone using Git:

$ git clone

Release tarballs are also available on the GitHub release pages.

See also

See the git book to learn how to work with Git repositories.

Install with setuptools#

Use pip to install the Python module into your virtual environment:

$ python3 -m pip install -e gsd

Build with CMake for development#

In addition to the setuptools build system. GSD also provides a CMake configuration for development and testing. You can assemble a functional Python module in the given build directory. First, configure the build with cmake.

$ cmake -B build/gsd -S gsd

Then, build the code:

$ cmake --build build/gsd

When modifying code, you only need to repeat the build step to update your build - it will automatically reconfigure as needed.


Use Ninja to perform incremental builds in less time:

$ cmake -B build/gsd -S gsd -GNinja


Place your build directory in /tmp or /scratch for faster builds. CMake performs out-of-source builds, so the build directory can be anywhere on the filesystem.


Pass the following options to cmake to optimize the build for your processor: -DCMAKE_CXX_FLAGS=-march=native -DCMAKE_C_FLAGS=-march=native.


When using a virtual environment, activate the environment and set the cmake prefix path before running CMake: $ export CMAKE_PREFIX_PATH=<path-to-environment>.

Run tests#

Use pytest to execute unit tests:

$ python3 -m pytest --pyargs gsd

Add the --validate option to include longer-running validation tests:

$ python3 -m pytest --pyargs gsd -p gsd.pytest_plugin_validate --validate


When using CMake builds, change to the build directory before running pytest:

$ cd build/gsd

Build the documentation#

Run Doxygen to generate the C documentation:

$ cd gsd
$ doxygen
$ cd ..

Run Sphinx to build the HTML documentation:

$ sphinx-build -b html gsd/doc build/gsd-documentation

Open the file build/gsd-documentation/index.html in your web browser to view the documentation.


When iteratively modifying the documentation, the sphinx options -a -n -W -T --keep-going are helpful to produce docs with consistent links in the side panel and to see more useful error messages:

$ sphinx-build -a -n -W -T --keep-going -b html gsd/doc build/gsd-documentation


When using CMake builds, set PYTHONPATH to the build directory before running sphinx-build:

$ PYTHONPATH=build/gsd sphinx-build -b html gsd/doc build/gsd-documentation

Embedding GSD in your project#

Using the C library#

gsd is implemented in a single C file. Copy gsd/gsd.h and gsd/gsd.c into your project.

Using the pure Python reader#

If you only need to read files, you can skip installing and just extract the module modules gsd/ and gsd/ Together, these implement a pure Python reader for gsd and HOOMD files - no C compiler required.