# Installation (/docs/python/installation)

Tracepanel for Python is the `tracepanel` package. It records the traces of
your Python app and sends them to the agent.

`tracepanel`, `tracepanel-agent` and `django-tracepanel` come out together, at
the same version. The current one is 0.2.0. `pip install tracepanel` installs
the agent of the same version. See the
[changelog](https://github.com/tracepanel/tracepanel-python/blob/main/CHANGELOG.md).

## Install the package [#install-the-package]

```bash
pip install tracepanel
```

For Django, you can install `django-tracepanel` instead. It has no code of its
own and installs the same package as `pip install "tracepanel[django]"`.

```bash
pip install django-tracepanel
```

The package also installs `tracepanel-agent`, the program that stores the
traces and serves the console. You don't install or start it yourself. See
[How it works](/docs/how-it-works). The agent comes as a wheel for the
platforms in [Supported versions](#supported-versions). On any other platform,
`tracepanel` installs without it.

## Add it to your app [#add-it-to-your-app]

<Tabs items={["Django", "FastAPI", "Flask"]}>
  <Tab value="Django">

Tracepanel supports Django 5.2, 6.0 and 6.1. Django 6.x needs Python 3.12 or
newer, and Python 3.15 works with Django 6.1 only.

Add the app to `INSTALLED_APPS`:

```python
# settings.py
INSTALLED_APPS += ["tracepanel.django"]
```

You don't add middleware or include URLs. The app puts its middleware first in
`MIDDLEWARE`, so it measures the whole request. It also serves
`/__tracepanel__/` itself.

Tracepanel is on when `DEBUG = True`. Start the server as usual:

```bash
python manage.py runserver
```

The [Django guide](/docs/django) covers the rest: what Tracepanel records in
Django, its settings and workers.

  </Tab>
  <Tab value="FastAPI">

Call `tracepanel.fastapi.install()` on your app:

```python
from fastapi import FastAPI

import tracepanel.fastapi

app = FastAPI(debug=True)
tracepanel.fastapi.install(app)
```

Tracepanel is on when the app has `debug=True`. A Starlette app works the
same way with `tracepanel.asgi.install(app)` and `Starlette(debug=True)`.

  </Tab>
  <Tab value="Flask">

Call `tracepanel.flask.install()` on your app:

```python
from flask import Flask

import tracepanel.flask

app = Flask(__name__)
tracepanel.flask.install(app)
```

Tracepanel is on in debug mode, so start the app with `flask run --debug` or
`app.run(debug=True)`.

  </Tab>
</Tabs>

Open a page of your app and click the badge in the corner to open the panel.
The console is at `/__tracepanel__/`.

## When it turns on [#when-it-turns-on]

Tracepanel records only in development. It turns on in one of these cases:

- Django runs with `DEBUG = True`.
- FastAPI or Starlette runs with `debug=True`, or Flask runs in debug mode.
- The command runs under `tracepanel run`.
- The `TRACEPANEL_ENABLED=1` variable is set.

Otherwise Tracepanel does nothing. It adds no middleware and patches nothing.
Falcon has no debug mode, so `tracepanel.falcon.install(app)` turns on only
under `tracepanel run`, with `TRACEPANEL_ENABLED=1` or with
`install(app, enabled=True)`.

## Run without changing your code [#run-without-changing-your-code]

`tracepanel run` starts a command with Tracepanel on. You don't change the
project:

```bash
tracepanel run python manage.py runserver   # Django
tracepanel run uvicorn app.main:app         # FastAPI, Starlette
tracepanel run flask --app app run          # Flask
tracepanel run gunicorn app:app             # Falcon
tracepanel run celery -A app worker         # a Celery worker
```

`tracepanel run` sets up each framework as your code imports it. For Django,
it adds `tracepanel.django` to `INSTALLED_APPS` while Django reads the
settings. For FastAPI, Starlette, Flask and Falcon, it installs Tracepanel on
each app as the app is created. Tracepanel is on even when `DEBUG` is off, so
you can look at production-like settings locally.

A worker or a script needs no framework. Under `tracepanel run`, every library
integration turns on as your code imports its library: the task queues,
SQLAlchemy, the database drivers, the HTTP clients, Redis, MongoDB, Strawberry,
OpenTelemetry and logging. See [Integrations](/docs/python/integrations).

## Workers and commands [#workers-and-commands]

A task or a management command has no page for the panel. Each task run and
each command ends with a line in the terminal and a link to its trace:

```text
tracepanel ▸ task newsletter.tasks.send_digest · success · 230 ms · 14 queries → http://127.0.0.1:52811/#/t/01M4…
```

The agent serves the console at that link even when no web server is running.
The agent picks a free port when it starts, so the port changes from run to
run. The trace's page in the console lists its issues.

## Supported versions [#supported-versions]

Tracepanel for Python supports Python 3.11 to 3.15. See
[Integrations](/docs/python/integrations#libraries) for the oldest version of
each framework and library it supports.

The agent ships for Linux, macOS and Windows:

- Linux on glibc: x86_64, arm64 (glibc 2.28 or newer), armv7, i686, ppc64le,
  s390x and riscv64 (glibc 2.31 or newer).
- Linux on musl, such as Alpine: x86_64, arm64, armv7, armv6 and i686.
- macOS: Apple silicon and Intel.
- Windows: x86_64, x86 and arm64.

On another platform, `pip install tracepanel` installs the package without the
agent. Build the agent from its source package, which needs Rust, with
`pip install tracepanel-agent`. Or point the `TRACEPANEL_AGENT_BIN` variable
at an agent you built.