Experimaestro is a Python framework designed for researchers and engineers who need to manage complex, large-scale experimental workflows without losing track of reproducibility.
Unlike traditional schedulers, Experimaestro focuses on the experimental logic: how configurations relate to each other and how results are organized.
Why Experimaestro?
- 🧩 Configuration-as-Code: Define your experiments using strongly-typed Python objects. Forget about fragile JSON/YAML files; benefit from IDE autocompletion, type checking, and recursive parameter management.
- 🛡️ Deduplication & Reproducibility: Every task is assigned a unique identifier based on its parameters. If you try to run the same experiment twice, Experimaestro knows—ensuring you never waste compute time on results you already have.
- 📁 Organized by Design: Results are automatically cached in a predictable directory structure derived from task identifiers. No more "results_v2_final_fixed.pt"—your file system stays as clean as your code.
- 🏗️ Built-in Scalability: Seamlessly transition from local testing to high-performance clusters. Use Connectors (Local, SSH) and Launchers (Direct, Slurm) to run the same experimental code across different environments.
- 📺 Real-time Monitoring: Track running and completed experiments as they progress, from a textual (terminal) UI or a web UI.
Documentation
The full documentation is at experimaestro-python.readthedocs.io:
- Tutorial — set up your first workspace and run a basic experiment (training a CNN on MNIST).
- Configurations & Tasks — define parameters, dependencies and execution logic.
- Launchers & Connectors — control where and how your code runs.
- How it differs from Slurm, OAR, Comet, Sacred and other experiment managers.
Screenshots
Textual interface (new in v2)
Web interface
Install
With pip
You can then install the package using pip install experimaestro
Develop
Checkout the git directory, then
pip install -e .
Coding assistant skill
Experimaestro ships an agent skill that teaches LLM coding assistants (Claude Code, Cursor, …) the framework's conventions and best practices. Install it with:
# Default: ~/.agents/skills/ (cross-client open standard)
experimaestro install-skill
# Install for a specific tool
experimaestro install-skill claude # ~/.claude/skills/
experimaestro install-skill cursor # ~/.cursor/skills/
# Install to several targets at once
experimaestro install-skill agents claude
# List available targets and what is already installed
experimaestro install-skill --list
Example
This very simple example shows how to submit two tasks that concatenate two strings. Under the curtain,
- A directory is created for each task (in
workdir/jobs/helloworld.add/HASHID) based on a unique ID computed from the parameters - Two processes for
Sayare launched (there are no dependencies, so they will be run in parallel) - A tag
yis created for the main task
# --- Task and types definitions
import logging
logging.basicConfig(level=logging.DEBUG)
from pathlib import Path
from experimaestro import Task, Param, experiment, progress
import click
import time
import os
from typing import List
# --- Just to be able to monitor the tasks
def slowdown(sleeptime: int, N: int):
logging.info("Sleeping %ds after each step", sleeptime)
for i in range(N):
time.sleep(sleeptime)
progress((i+1)/N)
# --- Define the tasks
class Say(Task):
word: Param[str]
sleeptime: Param[float]
def execute(self):
slowdown(self.sleeptime, len(self.word))
print(self.word.upper(),)
class Concat(Task):
strings: Param[List[Say]]
sleeptime: Param[float]
def execute(self):
says = []
slowdown(self.sleeptime, len(self.strings))
for string in self.strings:
with open(string.__xpm_stdout__) as fp:
says.append(fp.read().strip())
print(" ".join(says))
# --- Defines the experiment
@click.option("--port", type=int, default=12345, help="Port for monitoring")
@click.option("--sleeptime", type=float, default=2, help="Sleep time")
@click.argument("workdir", type=Path)
@click.command()
def cli(port, workdir, sleeptime):
"""Runs an experiment"""
# Sets the working directory and the name of the xp
with experiment(workdir, "helloworld", port=port) as xp:
# Submit the tasks
hello = Say.C(word="hello", sleeptime=sleeptime).submit()
world = Say.C(word="world", sleeptime=sleeptime).submit()
# Concat will depend on the two first tasks
Concat.C(strings=[hello, world], sleeptime=sleeptime).tag("y", 1).submit()
if __name__ == "__main__":
cli()
which can be launched with python test.py /tmp/helloworld-workdir
Ecosystem
A number of libraries and tools are built around experimaestro:
Datasets — datamaestro, a companion dataset manager, with plugins datamaestro_text, datamaestro_image, datamaestro_ml and datamaestro_ir.
Domain libraries
- xpm-torch — building blocks for PyTorch-based experiments.
- experimaestro-ir (xpmir) — information-retrieval tasks and configurations (built on xpm-torch). Specific experiments are their own projects in the xpmir organisation, e.g. splade, cosplade, cross-encoders and mice.
Tools & services — xpm-mlboard, lightweight services to monitor ML learning curves (TensorBoard, …).
Starting points — experiment-template (minimal skeleton) and experimaestro-demo (fuller MNIST example, also the tutorial).
See the Experimaestro projects guide for how to structure your own project.
1 maintainer
Metadata
1 maintainer
Release files for experimaestro 2.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| experimaestro-2.7.0.tar.gz | 2.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| experimaestro-2.7.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.1 MB
Release files / experimaestro-2.7.0.tar.gz
| Download URL | experimaestro-2.7.0.tar.gz |
|---|---|
| Size | 2.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4ca813a7bc154abdb9088bd09604c61b2a977712fcdbf74ecfc5fd4b3b5796da
|
|
BLAKE2b-256 checksum How to use checksums |
da57c926bc2b88d195834e3a15d1c04d0e273bd4e50bdf8b78b752c7c8b66459
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / experimaestro-2.7.0-py3-none-any.whl
| Download URL | experimaestro-2.7.0-py3-none-any.whl |
|---|---|
| Size | 1.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f2f6e3e7afdd0fa0ff67349671d4d6df7a2a41c4357979f06f595209063ba832
|
|
BLAKE2b-256 checksum How to use checksums |
90c025bb38172a7361b7b20b97df5b9e4706005925f7fcb6540dfca516284e4d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency log
