# Installation (/docs/django/installation)

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

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

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

`django-tracepanel` has no code of its own. It installs the same package as
`pip install "tracepanel[django]"`, with the agent that stores the traces and
serves the console. See [How it works](/docs/how-it-works).

`django-tracepanel`, `tracepanel` and `tracepanel-agent` share one version,
0.2.0 now. `pip install django-tracepanel` installs the matching ones.

The agent comes as a wheel for Linux, macOS and Windows on the common
processors. On another platform, `tracepanel` installs without it and keeps no
traces until you point it at an agent elsewhere with the `agent` setting. See
[Configuration](/docs/python/configuration).

### Upgrading from an earlier version [#upgrading-from-an-earlier-version]

An upgrade from 0.1 keeps the traces in `.tracepanel/`. The 0.1.0 agent
started a new store there, so the traces of an earlier version aren't carried
over.

## Add the app [#add-the-app]

```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, and serves `/__tracepanel__/`
itself.

## Start the server [#start-the-server]

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

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

The first line in the terminal shows what Tracepanel turned on, such as this
line in a project with Celery on Redis and Django REST framework:

```text
tracepanel ▸ on (DEBUG) · Django · logging, Database drivers, Redis, Celery, Django Tasks, DRF → console at /__tracepanel__/
```

Open any page, and a badge appears in the bottom right corner. Click it to
open the [panel](/docs/panel). The [console](/docs/console) is at
`/__tracepanel__/`.

An ASGI server, such as Uvicorn, Daphne or Granian, works the same way. So do
async views.

## Without changing the settings [#without-changing-the-settings]

`tracepanel run` starts a command with Tracepanel on, and you leave the
project as it is:

```bash
tracepanel run python manage.py runserver
```

It adds `tracepanel.django` to `INSTALLED_APPS` while Django reads the
settings, unless the app is there already. It turns Tracepanel on even when
`DEBUG` is off, so you can look at production-like settings locally.

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

A task worker or a management command has no page for the panel. Start the
worker as usual. With `tracepanel.django` in `INSTALLED_APPS` and `DEBUG` on,
each task run is a trace:

```bash
celery -A config worker
```

To trace a worker without changing the settings, or with `DEBUG` off, start it
with `tracepanel run`:

```bash
tracepanel run celery -A config worker
```

Each task run and each management 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 link goes to the console that the agent serves, so it works even when no
web server is running. The agent picks a free port each time it starts. It
stops after 30 minutes unused, and the next trace starts it again.

The dev server, shells, the test runner and task workers are left out as
commands of their own. See `ignore_commands` in
[Settings](/docs/django/settings).

## A frontend on Vite [#a-frontend-on-vite]

A single-page app on Vite's dev server, with Django as its API, gets the
panel from Tracepanel's Vite plugin. Install `@tracepanel/js` in the frontend
and name Django's console:

```ts
// vite.config.ts
import { tracepanel } from "@tracepanel/js/vite";

export default {
  plugins: [tracepanel({ console: "http://localhost:8000/__tracepanel__/" })],
};
```

The plugin serves Django's console on the frontend's origin, so the panel and
`EXPLAIN` work on the app's pages. It also records the pages in the browser,
and Django's console passes their traces on to the agent. See
[Pages in the browser](/docs/javascript/browser).