# Install the Bugstack Python SDK

The SDK reports uncaught server errors to Bugstack, which reproduces each one as a failing test in an isolated sandbox and sends a proven fix as a pull request. Setup for FastAPI, Flask, Django and plain Python, with the full config reference.

## Compatibility

Python 3.9+

Bugstack proves each fix by running your own tests with pytest in its verification sandbox: the reproduction test fails before the change and passes after it, with the rest of your suite green. [How the sandbox works](/docs/how-it-works#sandbox).

## Install

```
pip install bugstack
```

## Initialize

Call `bugstack.init()` once at startup with your API key and the Bugstack endpoint. Pass `endpoint` explicitly: the published SDK does not default to it yet.

```
import os
import bugstack

bugstack.init(
    api_key=os.environ.get("BUGSTACK_API_KEY", ""),
    endpoint=os.environ.get("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk"),
)
```

Report an error you handle yourself with `bugstack.capture_exception(e)`.

## FastAPI

Initialize, then add the middleware. It reports the exception and re-raises it, so FastAPI's own error handling still runs.

```
# In your main app file, after the FastAPI app is created:
import os
import bugstack
from bugstack.integrations.fastapi import FastAPIMiddleware

bugstack.init(
    api_key=os.environ.get("BUGSTACK_API_KEY", ""),
    endpoint=os.environ.get("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk"),
)
app.add_middleware(FastAPIMiddleware)
```

## Django

Add the middleware and initialize at the end of `settings.py`:

```
# settings.py
import os
import bugstack

bugstack.init(
    api_key=os.environ.get("BUGSTACK_API_KEY", ""),
    endpoint=os.environ.get("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk"),
)

MIDDLEWARE = [
    "bugstack.integrations.django.BugStackMiddleware",
    # ... your other middleware
]
```

## Flask

```
# In your main app file, after the Flask app is created:
import os
import bugstack
from flask import request
from werkzeug.exceptions import HTTPException

bugstack.init(
    api_key=os.environ.get("BUGSTACK_API_KEY", ""),
    endpoint=os.environ.get("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk"),
)

# Report unhandled errors (or add the capture call to your existing handler):
@app.errorhandler(Exception)
def handle_exception(e):
    if isinstance(e, HTTPException):
        return e  # 404s and other HTTP errors keep their own response
    bugstack.capture_exception(
        e,
        request=bugstack.RequestContext(
            route=request.url_rule.rule if request.url_rule else request.path,
            method=request.method,
        ),
    )
    return {"error": "Internal Server Error"}, 500
```

## Plain Python

For workers, scripts or any other Python process. Reports are sent from a background thread, so an exception that ends the process can exit before it is sent: report errors where you handle them.

```
import os
import bugstack
from bugstack.integrations.generic import install_hooks

bugstack.init(
    api_key=os.environ.get("BUGSTACK_API_KEY", ""),
    endpoint=os.environ.get("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk"),
)
install_hooks()  # uncaught exceptions in the main thread and in threads

# Or report an error you handle yourself:
try:
    process_job(job)
except Exception as e:
    bugstack.capture_exception(e, metadata={"job": job.id})
```

## Configuration Reference

Every option is a keyword argument to `bugstack.init()`.

Option

Type

Default

Description

`api_key`

str

—

Required. Your project API key (starts `bsk_`).

`endpoint`

str

a placeholder address

Where reports go. Set it to `https://dashboard.bugstack.ai/api/ingest/sdk`.

`project_id`

str

`""`

Explicit project identifier.

`environment`

str

`"production"`

Environment name sent with each report.

`enabled`

bool

`True`

Master switch for error capture.

`debug`

bool

`False`

Log SDK activity.

`dry_run`

bool

`False`

Log errors instead of sending them.

`deduplication_window`

float

`300.0`

Seconds during which the same error is sent only once. Bugstack also folds repeats within 24 hours.

`timeout`

float

`5.0`

HTTP timeout in seconds.

`max_retries`

int

`3`

Attempts per report, with backoff (1s, 2s).

`ignored_errors`

list

`[]`

Exception types, or substrings of messages, not to report.

`before_send`

Callable\[\[ErrorEvent\], ErrorEvent | None\]

`None`

Change an event before it is sent, or return `None` to drop it. This is how to remove anything you do not want sent.

`auto_fix`

bool

`False`

Sent with each report. What Bugstack does with a fix is set by the repository's autonomy level in Bugstack, not by this flag.

## Next Steps

-   [Python SDK Reference](/docs/sdk/python)
-   [Privacy & Data Handling](/docs/privacy)
-   [How Bugstack Works Under the Hood](/docs/how-it-works)
-   [Python SDK Overview](/for/python)

## Get started

Sign up with GitHub and start the 14-day trial, or book a demo and we set it up with you. Once the SDK is in, an uncaught server error starts a fix: specialist agents work out the cause and write a small change, it arrives as a pull request that runs through your CI, and what happens next depends on the autonomy level you set. Connecting the repository also starts repository scanning.

[Get started](https://dashboard.bugstack.ai/login) [Book a demo](/demo)