# How to Set Up Auto-Reload for Python Projects


This guide covers auto-reload setup for the most common Python development scenarios. For background on how reloading works and why Python's story is fragmented, see [How Does Hot Reloading Work in Python?](https://pydevtools.com/handbook/explanation/how-does-hot-reloading-work-in-python.md).

## Django

### Step 1

Django's development server auto-reloads by default:

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

### Step 2

For faster change detection, install Watchman and the `pywatchman` Python package:

```bash
brew install watchman
uv add --dev pywatchman
```
On Linux, see the [Watchman installation docs](https://facebook.github.io/watchman/docs/install) for platform-specific instructions, then install `pywatchman` the same way.
Django's Watchman integration is Linux/macOS only. On Windows, Django uses `StatReloader` (polling), which works but is slower to detect changes.
## Flask

### Step 1

Enable the reloader:

```bash
uv run flask --app myapp run --debug
```

Or in code:

```python
app.run(debug=True)
```

The `--debug` flag enables both the reloader and the debugger. To enable only the reloader without the debugger, use `--reload` instead of `--debug`.

### Step 2

Flask reloads on `.py` file changes. Templates are auto-reloaded in debug mode by default. Outside debug mode, set `TEMPLATES_AUTO_RELOAD=True` in your app config to enable template reloading.

## FastAPI / Uvicorn

### Step 1

Run with the `--reload` flag:

```bash
uv run uvicorn main:app --reload
```

### Step 2

Scope watched directories to speed up detection:

```bash
uv run uvicorn main:app --reload --reload-dir src
```

### Step 3

For more control, specify file extensions to watch. Note that `--reload-include` and `--reload-exclude` require `watchfiles` to be installed (included in `uvicorn[standard]`):

```bash
uv add uvicorn[standard]
uv run uvicorn main:app --reload --reload-include "*.py" --reload-include "*.html"
```

## Generic Python Scripts

For scripts that aren't web servers, use `watchfiles` (the library Uvicorn uses internally).

### Step 1

Install watchfiles:

```bash
uv add --dev watchfiles
```

### Step 2

Use the CLI to watch and re-run a script:

```bash
uv run watchfiles "python main.py" .
```

This watches the current directory for changes and re-runs `python main.py` on every change.

### Step 3

Filter which files trigger a reload:

```bash
uv run watchfiles --filter python "python main.py" src
```

> [!TIP]
> `watchfiles` can also be used as a Python library for programmatic file watching. See the [watchfiles documentation](https://watchfiles.helpmanual.io/) for the API.

## [IPython](https://pydevtools.com/handbook/reference/ipython.md) / Jupyter Auto-Reload

For interactive REPL sessions where imported modules should pick up code changes without restarting the kernel:

### Step 1

Load the autoreload extension:

```python
%load_ext autoreload
%autoreload 2
```

### Step 2

Now any module you import will be automatically reloaded before each cell execution if the source file has changed:

```python
from mypackage import my_function
my_function()  # edit mypackage/my_function.py, run again — picks up changes
```

> [!NOTE]
> `%autoreload 2` reloads all modules. Use `%autoreload 1` to only reload modules that were imported with `%aimport`. See the [IPython autoreload docs](https://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html) for all modes.

## Using jurigged for Live Code Patching

For a more advanced approach that patches running code without restarting:

### Step 1

Install jurigged:

```bash
uv add --dev jurigged
```

### Step 2

Run your script through jurigged:

```bash
uv run jurigged main.py
```

Code changes to functions and methods are patched into the running process. Module-level code and class definitions may require a restart.

> [!WARNING]
> Live code patching preserves in-memory state, which can cause inconsistencies if you change data structures or module-level initialization. Use process-restart approaches (watchfiles, framework reloaders) when you need a clean slate.