Skip to content
Back to top

# Installation

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 `pygsd.py`.

## Binaries

### conda-forge package

gsd is available on conda-forge for the linux-64, linux-aarch64, linux-ppc64le, osx-64, osx-arm64 and win-64 architectures:

Pixi

    pixi add gsd

Micromamba

    micromamba install gsd

Mamba

    mamba install gsd

### PyPI

Install gsd binaries from PyPI into a virtual environment:

uv

    uv pip install gsd

pip

    python3 -m pip install gsd

## Compile from source

To build gsd from source:

1. Obtain the source:

       git clone git@github.com:glotzerlab/gsd.git

2. Change to the repository directory:

       cd gsd

3. uv

   Install with uv:

       uv pip install .

   CMake

   Install prerequisites and Build with CMake for development:

       micromamba install cmake cython ninja numpy python pytest

       cmake -B build -S . -GNinja
       cd build
       ninja

To run the tests:

1. Run tests:

       python3 -m pytest gsd

To build the documentation from source:

1. Install prerequisites:

       micromamba install breathe doxygen sphinx furo ipython sphinx-copybutton

2. Build the documentation:

       cd {{ path/to/gsd/repository }}

       doxygen
       sphinx-build -b html doc html

The sections below provide details on each of these steps.

### Install prerequisites

gsd requires a number of tools and libraries to build.

General requirements:

- C compiler (tested with gcc 10-14, clang 10-18, Visual Studio 2019-2022)

- Python >= 3.11

- numpy >= 2.0.0

- Cython >= 3.1

To execute unit tests:

- pytest >= 3.9.0

To build the documentation:

- breathe

- Doxygen

- furo

- IPython

- Sphinx

- sphinx-copybutton

- an internet connection

### Obtain the source

Clone using Git:

    git clone git@github.com:glotzerlab/gsd.git

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 uv

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

    cd {{ path/to/gsd/repository }}

    uv pip install .

### Build with CMake for development

GSD also provides CMake scripts for development and testing that build a functional Python module in the build directory. First, configure the build with `cmake`:

    cd {{ path/to/gsd/repository }}

    cmake -B build -S . -GNinja

Then, build the code:

    cd build
    ninja

Execute `ninja` to rebuild after you modify the code. `ninja` will automatically reconfigure as needed.

Tip

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

Warning

When using a `conda-forge` environment for development, make sure that the environment does not contain `clang`, `gcc`, or any other compiler or linker. These interfere with the native compilers on your system and will result in compiler errors when building, linker errors when running, or segmentation faults.

### Run tests

Use pytest to execute unit tests:

    python3 -m pytest gsd

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

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

### Build the documentation

Run Doxygen to generate the C documentation:

    cd {{ path/to/gsd/repository }}

    doxygen

Run Sphinx to build the HTML documentation:

    PYTHONPATH=build sphinx-build -b html doc html

Open the file `html/index.html` in your web browser to view the documentation.

Tip

Add the sphinx options `-a -n -W -T --keep-going` to produce docs with consistent links in the side panel and provide more useful error messages.

## 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

The Python modules `gsd/pygsd.py` and `gsd/hoomd.py` implement a pure Python reader for gsd and HOOMD files.