Quickstart: Record and Replay Your First Python Crash

This guide walks you through installing Slomo, wiring it into a Python app, and using the CLI to find and diagnose a real crash — all in about five minutes. You don’t need an account, a running server, or any external infrastructure.

Install Slomo

Install Slomo from PyPI into your active environment:

pip install slomo

Slomo requires Python 3.12 or later. If you’re on an older version, see the Installation page for guidance.

Add two lines to your app

Import slomo and call enable() at the very top of your application’s entry point — before any other application code runs:

import slomo          
slomo.enable()        

That’s the entire integration. From this point on, Slomo automatically records:

Every function call in your project code
Unhandled exceptions, including local variables from the crashing frame
SQL queries (sqlite3, SQLAlchemy, and compatible ORMs)
HTTP requests made with requests or httpx
Log records at WARNING level and above
Session metadata: argv, cwd, Python version, hostname, PID, and exit status

Run your app and trigger a crash

To see Slomo in action, save the following as app.py in an empty directory and run it. The script has a deliberate bug — checkout() crashes when the requested SKU is missing from the database.

app.py

import sqlite3
import slomo
from slomo import track

slomo.enable()

@track
def load_inventory(db, sku):
    return db.execute(
        "SELECT sku, qty FROM inventory WHERE sku = ?", (sku,)
    ).fetchone()

@track
def checkout(db, sku):
    inventory = load_inventory(db, sku)
    return {"sku": inventory[0], "qty": inventory[1]}  # BUG: inventory can be None

db = sqlite3.connect(":memory:")
db.execute("CREATE TABLE inventory (sku TEXT PRIMARY KEY, qty INTEGER)")
db.execute("INSERT INTO inventory VALUES ('widget', 5)")

checkout(db, "widget")  # succeeds
checkout(db, "gadget")  # crashes — 'gadget' is not in the database

python app.py

When the script exits (even after a crash), Slomo writes the full session recording to .slomo/ in the current directory. The directory is created automatically on the first run.

Explore the recording with the CLI

With the recording on disk, use the Slomo CLI to understand what went wrong.List all recorded crashes:

slomo issues

┃ issue        ┃ title                                      ┃ category       ┃ count ┃
│ SM-8b6f710a  │ TypeError: 'NoneType' object is not subsc… │ Null Reference │     5 │

Slomo groups crashes by fingerprint so you can see at a glance which issues are recurring and how often.Get a root-cause diagnosis:

slomo doctor SM-8b6f710a

Category              Null Reference  (95% confidence)
Occurrences           5  (5 unhandled) across 5 session(s)
Likely root cause     TypeError raised in checkout() at app.py:14.
                      Variable 'inventory' was None at the crash site.
First bad function    checkout()
First bad variable    inventory
Suggested fix         Guard against None before the failing access at app.py:14
                      — trace where the value is produced and handle the missing case.
Context just before the crash:
  13:04:52.133 sql.query   SELECT sku, qty FROM inventory WHERE sku = ?
  13:04:52.133 sql.result  0 rows, 9µs

slomo doctor pinpoints the first function and variable that went wrong, explains why the crash happened, and suggests a fix — all from the local recording, with no network call.Step through the crash interactively:

slomo replay SM-8b6f710a

The replay command opens an interactive terminal UI that lets you step forward and backward through every function call, inspect arguments and return values, and see exactly how the program reached the crash.

Next steps

Run slomo init in your project directory to scaffold a .slomo/config.toml file with all available options and inline comments. This is optional — Slomo works without any configuration — but useful when you want to tune what gets recorded or where sessions are stored.

Now that you’ve seen Slomo in action, here’s where to go next:

Installation — pip/uv/pipx setup, Python version requirements, and optional integrations
Core Concepts — understand how sys.monitoring and PEP 669 power zero-config instrumentation
CLI Reference — full documentation for every Slomo command

Get Started

Core Concepts

Recording

Investigating

Configuration

Quickstart: Record and Replay Your First Python Crash

Next steps

​Next steps

Next steps