gsd binaries are available 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 for the linux-64, linux-aarch64, linux-ppc64le, osx-64, osx-arm64 and win-64 architectures. Install with:

$ mamba install gsd


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 sphinx-copybutton
  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 10-14, clang 10-18, Visual Studio 2019-2022)

  • Python >= 3.9

  • numpy >= 1.19.0

  • Cython >= 0.22

To build the documentation:

  • breathe

  • Doxygen

  • furo

  • IPython

  • Sphinx

  • sphinx-copybutton

  • 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.