pyslurm: a Python binding to the Slurm C API

The version number is a compatibility contract, not a library version

pyslurm is the Python client library for the Slurm Workload Manager, and the versioning scheme is the first thing to understand about it.

PySlurm uses the format X.Y.Z where X.Y tracks the Slurm major release and Z is PySlurm's own patch increment, reset to 0 on each new Slurm major release.

| PySlurm | Slurm |
|---|---|
| 25.11.x | 25.11.x |
| 24.05.x | 24.05.x |
| 23.11.x | 23.11.x |

That table is the whole compatibility story. A PySlurm release is built against a specific Slurm release, and the major and minor components are identical on both sides. The patch component is the only part that moves independently, and it moves forward only, so a 25.11.2 client is a later build of the same Slurm 25.11 line.

The reason this matters is the implementation. PySlurm is not a reimplementation of the scheduler and it does not parse text output. It is a binding to the Slurm C API, which means the C library it links against has to expose the same entry points the binding expects. The Slurm C API changes between releases, so a binding built for one minor version is not a safe drop-in for another.

The primary language recorded for the repository is Cython, and the dependency on the C headers is visible in the requirements. The stated requirements are Slurm 25.11.x with the shared library and header files, and Python 3.6 or newer.

The current releases are v25.11.0 on 2026-02-13, v25.11.1 on 2026-04-01 and v25.11.2 on 2026-04-15, and the last push to the repository was on 2026-09-04.

Building against Slurm's headers, and the two environment variables that fix it

PySlurm requires the Slurm development headers and shared library at build time, which is the one genuinely different thing about installing it compared with a normal Python package.

If you have slurm-devel installed in the default paths, you can skip the configuration step entirely. By default, PySlurm looks in /usr/include for the Slurm header files, which is slurm/slurm.h, and in /usr/lib64 for the Slurm shared library, which is libslurmfull.so.

If your Slurm installation is not in the default paths, you set these before installing:

export SLURM_INCLUDE_DIR=/path/to/slurm/include
export SLURM_LIB_DIR=/path/to/slurm/lib

Those two variables are the whole configuration surface, and the defaults in the build script match what is written in the README. The setup.py in the repository root is where the search happens, with a SlurmConfig class holding a lib_dir that starts at /usr/lib64 and an inc_dir that starts at /usr/include, a list of lib_dir_search_paths, and a _find_hdr method that raises a RuntimeError saying Cannot locate the header in the include directory if the file is not there. The _search_lib method appends the directory to the search path when the shared library is not present and prints a message naming the library when it is found.

The library name it looks for is fixed:

SLURM_LIB = "libslurmfull"

The install from PyPI is the ordinary command:

pip install pyslurm

And the install from source is a clone plus a build script:

git clone https://github.com/PySlurm/pyslurm.git && cd pyslurm
scripts/build.sh

The build script takes a -j flag for parallel compilation, or you can set PYSLURM_BUILD_JOBS instead:

scripts/build.sh -j4

The build backend is setuptools with a Cython requirement of 0.29.37 or newer, and the setup.py keeps that same minimum in a constant named CYTHON_VERSION_MIN with a comment to keep it in sync with pyproject.toml, which tells you the two files have to agree and that the author knew it was a trap.

What the examples directory tells you about the API surface

The examples are the clearest available description of what the library exposes, and there are a lot of them, each named after the operation it performs.

The read side is well covered. There are jobs_list.py and job_test.py for the core job queries, node_list.py and node_update.py for nodes, partition_list.py, partition_create.py, partition_update.py and partition_delete.py for partitions, reservation_create.py and reservation_delete.py for reservations, and jobs_list.py variants. There is blocks_list.py and blocks_list2.py, jobsteps_list.py and jobsteps_layout.py for the accounting side, and a set of listdb_ files for the database, listing cluster, events, jobs, qos and reservations.

The write side is there too. cancel_job.py, checkpoint_job.py and controllers.py cover the operations that change state, licenses.py covers the license query, hostlist.py shows how a host list expression is handled, and debug_levels.py suggests there is a way to control the verbosity of the library's own logging.

That last one is worth noting for a binding like this. When you are calling a C library, a stray debug level can flood your logs, and having a script that demonstrates the control is a sign the library treats it as a first-class concern rather than something you patch by hand.

The rest of the repository supports those examples. The docs/ directory and mkdocs.yml drive the documentation, examples/ holds the scripts, tests/ and tox.ini cover the test suite, and the presence of a valgrind-pyslurm.supp file tells you the project is checked under Valgrind, which is standard practice for a C extension and is a good sign about the memory handling in the Cython layer. There is also an UPGRADE_C_API.rst, which is the documentation you want when a new Slurm release changes the C API underneath you.

A containerised Slurm, and how the project is packaged

The docker-compose.yml at the repository root gives you a Slurm to develop against, and the configuration is simple on purpose.

services:
  slurm:
    image: ${SLURM_DOCKER_IMAGE:-giovtorres/slurm-docker:25.11.2}
    hostname: slurmctl
    container_name: slurmctl
    privileged: true
    stdin_open: true
    tty: true
    working_dir: /pyslurm
    environment:
      MYSQL_USER: slurm
      MYSQL_PASSWORD: password
    volumes:
      - ${PWD}:/pyslurm:z

The image is parameterised through SLURM_DOCKER_IMAGE with a default of the Slurm 25.11.2 container, which matches the current release line of the library. The service runs privileged with a tty and stdin open, because a Slurm controller needs to start daemons and talk to the other nodes in the cluster. The working directory is /pyslurm and the whole repository is bind mounted there, so a Cython extension you rebuild is immediately visible inside the container without a rebuild of the image. The MYSQL_USER and MYSQL_PASSWORD environment variables are for the accounting database.

Packaging is a mix of modern and traditional. The pyproject.toml carries the project metadata, with a dynamic version and a licence of GPL-2.0-only, and the authors listed as Mark Roberts, Giovanni Torres and Toni Harzendorf, who is also the maintainer. The build requirements are setuptools with wheel, Cython and packaging.

The classifiers are more revealing than they look. The development status is Production/Stable, the operating system is POSIX Linux only, and the listed Python versions run from 3.6 through 3.12 even though the project metadata also carries the newer 3.12 classifier, which is a small inconsistency in a library whose whole selling point is being careful about compatibility. The keywords list HPC, Batch Scheduler, Resource Manager, Slurm and Cython, and the topics cover software development libraries, Python modules and distributed computing.

The GPL-2.0-only licence is the one to note for adoption. For a library you import inside a larger application, the GPL's copyleft reaches the application, which is a different position from a permissive licence and worth confirming with whoever handles licensing in your organisation.

Editorial conclusion

pyslurm suits a site that already runs Slurm and wants to drive the scheduler from Python without parsing the output of command line tools, because it binds the actual C API and returns structured data. It does not suit you if you want a pure Python client with no build step, since it needs the Slurm headers and shared library at install time, and it does not suit a Slurm version other than the one your PySlurm release targets. Before you install, check the version mapping table and match the Slurm release exactly, and set SLURM_INCLUDE_DIR and SLURM_LIB_DIR if your Slurm is not in the default paths.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. PySlurm/pyslurm on GitHub
4. README
5. Releases