Pre-release

This release is a pre-release and may not be stable for production use.

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)

Experiments screen — Experiments overview: monitor (local or SSH) running and completed experiments

Jobs screen — Jobs view: track job status, progress, and dependencies

Job details screen — Job details: inspect individual job parameters and output

Logs screen — Logs view: real-time log streaming for running tasks

Services screen — Services view: monitor background services and their status

Web interface

Web UI tasks screen — Tasks view: filter, sort and monitor jobs by status, tags, duration and CO₂, with live progress and per-job logs/actions

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 Say are launched (there are no dependencies, so they will be run in parallel)
A tag y is 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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

experimaestro-2.6.2b0.tar.gz (2.4 MB view details)

Uploaded Jul 31, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

experimaestro-2.6.2b0-py3-none-any.whl (1.7 MB view details)

Uploaded Jul 31, 2026 Python 3

File details

Details for the file experimaestro-2.6.2b0.tar.gz.

File metadata

Download URL: experimaestro-2.6.2b0.tar.gz
Upload date: Jul 31, 2026
Size: 2.4 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for experimaestro-2.6.2b0.tar.gz
Algorithm	Hash digest
SHA256	`865f459e7e7b6f74f6b401f6a70a5024f87f8300041c40a92fd52bddc3d77d9f`
MD5	`44b80dc33435e24f48635902f9ccd76d`
BLAKE2b-256	`5260bba222b04a6f199c0dee2aca1b9905665c7f41567338f093dce6cd9c38fb`

See more details on using hashes here.

Provenance

The following attestation bundles were made for experimaestro-2.6.2b0.tar.gz:

Publisher: python-publish.yml on experimaestro/experimaestro-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: experimaestro-2.6.2b0.tar.gz
- Subject digest: 865f459e7e7b6f74f6b401f6a70a5024f87f8300041c40a92fd52bddc3d77d9f
- Sigstore transparency entry: 2299919785
- Sigstore integration time: Jul 31, 2026
Source repository:
- Permalink: experimaestro/experimaestro-python@9275b52d4df39b35e993e4c2f0e27738c6c813f3
- Branch / Tag: refs/tags/v2.6.2b0
- Owner: https://github.com/experimaestro
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-publish.yml@9275b52d4df39b35e993e4c2f0e27738c6c813f3
- Trigger Event: release