Skip to main content

ploom

CI Coverage CodSpeed Python License Ruff uv

Find thread bugs in Python. Replay the schedule that failed.

A thread bug depends on which thread runs next. A test can pass a thousand times and still miss the bad order. Ploom runs your test under a controlled scheduler. It tries every order of ploom operations, stops at the first failure, and saves that order as a JSON trace. Replay the trace to get the same failure again.

Documentation · Guide · Guarantees · Python API · Development

Install

Ploom is not on PyPI yet. Install it from GitHub:

uv add --dev "ploom @ git+https://github.com/AdilZouitine/ploom.git"

Example: two withdrawals from one account

Mathieu and Lucas share an account that holds 100. They both withdraw 100 at the same time. Only one withdrawal must succeed.

import ploom


def scenario():
    balance = ploom.SharedCell(100)

    def withdraw():
        if balance.read() >= 100:
            balance.write(balance.read() - 100)

    mathieu = ploom.Thread(target=withdraw)
    lucas = ploom.Thread(target=withdraw)
    mathieu.start()
    lucas.start()
    mathieu.join()
    lucas.join()
    assert balance.read() >= 0, "the account is overdrawn"


ploom.check(scenario)

SharedCell holds a value that the threads share. ploom.Thread is a thread that ploom schedules. With threading.Thread, this code passes almost every time. Ploom tries the possible orders and finds the bad one in a few seconds:

ploom.exploration.ModelCheckError: builtins.AssertionError: the account is overdrawn
Original trace: .ploom/f981…-original.json
Minimized trace: .ploom/f981…-minimized.json

The minimized trace shows the bad order:

  1. Lucas reads the balance: 100. He can withdraw.
  2. Mathieu reads the balance: 100. He can withdraw.
  3. Mathieu withdraws. The balance is 0.
  4. Lucas withdraws. The balance is -100.

To fix the bug, hold a lock during the check and the withdrawal:

lock = ploom.Lock()

def withdraw():
    with lock:
        if balance.read() >= 100:
            balance.write(balance.read() - 100)

Now all 127 orders pass, and ploom.check returns the exploration statistics. examples/bank_account.py contains the version without the lock.

Use it in pytest

The ploom_check fixture explores a scenario inside a test:

def test_withdraw(ploom_check):
    ploom_check(scenario)

When the test fails, ploom prints the command that replays the failure:

ploom first failure: .ploom/ID-original.json
Replay: pytest tests/test_bank.py::test_withdraw --ploom-replay=.ploom/ID-original.json

Replay a failure

Replay runs one saved schedule. It does not search. Run the printed command:

uv run pytest tests/test_bank.py::test_withdraw --ploom-replay=.ploom/ID-original.json

A module-level scenario can also use the command line:

uv run python -m ploom check examples.bank_account:scenario
uv run python -m ploom replay .ploom/ID-minimized.json

Replay stops with ReplayDivergenceError if the scenario's source file, the Python minor version, or the recorded operations changed.

How it works

  1. Each ploom operation is a scheduling point. Only one task runs at a time, so the result does not depend on the GIL.
  2. A depth-first search tries each runnable task at each scheduling point.
  3. Each schedule runs in a fresh Python process. Python state from one schedule does not leak into the next. All processes use the same hash seed, so set order does not change between schedules.
  4. At the first failure, ploom saves the trace. Then it looks for the same failure with fewer preemptions and saves a minimized trace. A preemption is a switch away from a task that could continue.
  5. A search limit raises IncompleteExplorationError. A limit never counts as a pass.

A fresh process costs about 0.1 seconds per schedule. Keep scenarios small. For larger scenarios, set Config(max_preemptions=2) to explore every schedule with at most two preemptions.

Scope

Area Supported
Threads Thread(target, args, kwargs), start, join, is_alive
Locks Lock: blocking and nonblocking acquire, release, locked, with
Shared state SharedCell reads and writes of immutable values, yield_now()
Entry points Python API, pytest fixture, python -m ploom
Interpreters Standard CPython 3.13 and 3.14, free-threaded CPython 3.14

Ploom sees only ploom operations, and it models them as sequentially consistent. It does not see threading locks, Event, Queue, I/O, or weak-memory effects. It does not detect data races. Your assertions find the bugs.

Ploom does not roll back files, network calls, or other external effects between schedules.

Develop

uv sync --locked
make check

Run make docs to build the documentation. The development guide covers benchmarks and CI.

Acknowledgment

Ploom is inspired by Loom, the concurrency testing library for Rust. Loom showed how to explore schedules and reproduce failures. Ploom defines its own Python operations. It does not implement Loom's C11 memory model or its partial-order reduction.

License

Ploom is licensed under Apache-2.0.

Metadata

Release files for ploom 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ploom 0.1.0
File Size Uploaded Provenance Actions
ploom-0.1.0.tar.gz 31.1 kB With provenance Details for ploom-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ploom 0.1.0
File Interpreter ABI Platform Actions
ploom-0.1.0-py3-none-any.whl Python 3 none any Details for ploom-0.1.0-py3-none-any.whl

Total release size: 68.7 kB

Release files / ploom-0.1.0.tar.gz

Download URL ploom-0.1.0.tar.gz
Size 31.1 kB
Tags Source
SHA-256 checksum
How to use checksums
ae6c611ac52780e42f7024fc5c7a12f81d25b9b454b7f0cdf70fe3cc1abd0cbd
BLAKE2b-256 checksum
How to use checksums
6d1036edc11c1d56915bdce7f20a6d79cf1824114f11fcfe6600596755546a91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 26, 2026.

Transparency log

Release files / ploom-0.1.0-py3-none-any.whl

Download URL ploom-0.1.0-py3-none-any.whl
Size 37.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
41f63fbc069ffb97b1ddc3e7afe8ca39a1f21b537b2e2647ba81b82a0b0faaec
BLAKE2b-256 checksum
How to use checksums
04a23fc103cf0f4469a58c80c47cdc173948ae749624d768f2f08dee77c5be35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 26, 2026.

Transparency log

Security for ploom 0.1.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ploom-0.1.0.tar.gz

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 26, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page