ploom
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:
- Lucas reads the balance: 100. He can withdraw.
- Mathieu reads the balance: 100. He can withdraw.
- Mathieu withdraws. The balance is 0.
- 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
- Each ploom operation is a scheduling point. Only one task runs at a time, so the result does not depend on the GIL.
- A depth-first search tries each runnable task at each scheduling point.
- 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.
- 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.
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.