How to Set Up Auto-Reload for Python Projects

by Tim Hopper

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?.

Django

Step 1

Django’s development server auto-reloads by default:

uv run python manage.py runserver

Step 2

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

brew install watchman
uv add --dev pywatchman

On Linux, see the Watchman installation docs 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:

uv run flask --app myapp run --debug

Or in code:

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:

uv run uvicorn main:app --reload

Step 2

Scope watched directories to speed up detection:

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]):

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:

uv add --dev watchfiles

Step 2

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

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:

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 for the API.

IPython / 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:

%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:

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 for all modes.

Using jurigged for Live Code Patching

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

Step 1

Install jurigged:

uv add --dev jurigged

Step 2

Run your script through jurigged:

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.

Last updated on April 7, 2026

How to set up a Python monorepo with uv workspaces How to set up pre-commit hooks for a Python project

Please submit corrections and feedback...