Retrace

Production-Safe Record-Replay for Python.

pip install retracesoftware.proxy

no code changes, minimal overhead.

Get started

Star on GitHub

PREVIEW RELEASE: Python 3.11 only | Apache 2.0

Backed by Preston-Werner Ventures

One line install

Pip-install.

Production safe

Python level capture

Minimal Overhead

Optimised C. See benchmarks.

Deterministic Replay

Exact reproduction

VSCode Integration

Time-travel debugging

Debug Anything

Every thread, every call

Quick Start

Install

Copy code

python -m pip install

--upgrade pip

python -m pip install

--upgrade retracesoftware.proxy requestspython -m retracesoftware.autoenable

# Installs Retrace and configures your Python 3.11 environment.

Record

Copy code

							RETRACE=1

							RETRACE_RECORDING_PATH=record
ing \

							python your_app.py

							# Records your application execution to ./recording/
Replace your_app.py with your Python script.

Replay

Copy code

							# CLI replay

							cd recording/run

							python -m retracesoftware --recording

							# VS Code debugging

							code recording/replay.code-workspace

							# Press F5 to start debugging

							# Replays the recording deterministically.

							Debug with breakpoints in VS Code or run via CLI.

Full tutorial: Flask demo with crash replay (10 minutes)

Try the Quickstart

Q&A Section

Getting started

Is it hard to set up?

No. It’s a pip‑install agent — enable with an env var, run your app, and you’re recording. No code changes.

Do I need to change my code?

No. Retrace attaches at the Python runtime level (custom C proxy) and works with your existing app.

What Python versions work?

Our preview is Python 3.11 only, with Django/Flask and 60+ popular libraries tested. In a few months we will also have Retrace working with 3.9, 3.10 and 3.12.

Production Concerns

Can I run Retrace safely in production?

Yes. Retrace is designed for production: it records deterministically at the Python runtime layer (not ptrace/libc) — the first known prod‑safe approach of its class.

How much overhead does it add?

Measured latency overhead is under ~2% on Django/Flask workloads.

How does Retrace handle sensitive data?

Retrace records I/O; you control trace files. For stricter environments we support on‑prem deployment.

How It’s Different

How is this different from logging or APM tools?

Logs/APM show symptoms and depend on developers remembering to instrument; they can be incomplete and don’t let you step the program backward. Retrace gives you a deterministic replay of the exact execution so you can inspect the real code path and state.

Can it catch race conditions and flaky tests?

Yes. Retrace captures thread/signal interactions and replays them deterministically, so you can reproduce timing‑sensitive failures and step through them.

Open Source & Community

Is it really open source?

Yes. The Record‑Replay core is open source and released under an Apache 2.0 licence.

Why is this a preview release?

We’re opening the OSS agent early to gather installs/feedback while we finalise broader Python version and library coverage, and production hardening before GA.

How can I contribute?

Star the repo, try pip install retrace, file issues/PRs on GitHub, and use the forum for Q&A. Good first issues: library compatibility reports, minimal repros of failures, docs/examples improvements.

How does it work?

During the recording phase, Retrace captures all I/O interactions and the program’s structure, storing everything needed to enable deterministic replay.

Using a custom proxy system, Retrace ensures that the program can be re-executed with the recorded I/O, faithfully reproducing its original behavior.

Your Production App
running normally