Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Uvicorn --reload never restarts when you edit code in a Docker container

ErrorThe server runs in the container, but saving a file does not print a reload line

Short answer

Uvicorn can only reload files that change inside the container. Most often the code was copied into the image, so host edits never arrive; mount the folder or use Compose Watch. If it is mounted but nothing fires, file events are not delivered, so force watchfiles polling. Also check that your file type and folder are in the watch list.

  • Applies to Uvicorn 0.3x, watchfiles 1.x, FastAPI 0.11x, Docker Compose 2.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the file inside the container with the one on your host. If they differ, the cause is the mount, not uvicorn.

    docker compose exec web sh -c 'ls -l /app/main.py; md5sum /app/main.py'
    md5sum ./main.py
  2. 2Match what you see, then jump to its fix

    1. 1The two md5sum values differ after you save the fileThe code is copied into the image, not mountedFix
    2. 2You use develop.watch, and changes never appear inside the containerCompose Watch is not sync-ing, or the image lacks what it needsFix
    3. 3The files match in both places, but uvicorn prints no reload lineFile-change events do not reach the watcherFix
    4. 4Python edits reload, but a template, .env or config change does not; or a folder outside the current directory is ignoredThe watcher is set to look at other files or foldersFix

What does the error look like?

  • The server runs in the container, but saving a file does not print a reload line
  • Edits show on the host, but the container serves the old code

Cause 1 of 4

The code is copied into the image, not mounted

1Check

A COPY step bakes the files into the image. A host edit does not reach a running container unless a bind mount (or a Compose sync rule) links the folders.

docker compose config | grep -A6 -i 'volumes\|develop'

2Fix

Bind-mount the project folder over the code path. Compose Watch is the other documented route: it syncs changed files into the container.

services:
  web:
    build: .
    command: uvicorn main:app --host 0.0.0.0 --reload
    volumes:
      - ./:/app

3Verify

Edit a file, then watch the container log for a reload line.

docker compose logs -f web

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 4

Compose Watch is not sync-ing, or the image lacks what it needs

1Check

Compose Watch needs stat, mkdir and rmdir in the image, a container USER that can write to the target, no glob patterns, and it does not track services that use a prebuilt image: attribute.

docker compose watch

2Fix

Use a sync rule with a plain path, and copy files with the right owner. Start it with docker compose up --watch or docker compose watch.

services:
  web:
    build: .
    command: uvicorn main:app --host 0.0.0.0 --reload
    develop:
      watch:
        - action: sync
          path: ./app
          target: /app/app
        - action: rebuild
          path: requirements.txt

3Verify

Edit a file under ./app and see it update in the container.

docker compose exec web cat /app/app/main.py

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 4

File-change events do not reach the watcher

1Check

watchfiles uses file system notifications and falls back to polling only when it cannot use them. Uvicorn's docs say that under WSL you may need to set WATCHFILES_FORCE_POLLING for edits to trigger reloads.

docker compose exec web env | grep WATCHFILES

2Fix

Turn polling on for the container. Any value other than false, disable or disabled enables it.

services:
  web:
    environment:
      WATCHFILES_FORCE_POLLING: "true"

3Verify

Save a file and see the reload line.

docker compose up -d && docker compose logs -f web

Confirmed by watchfiles.helpmanual.io

Did this fix it?

Cause 4 of 4

The watcher is set to look at other files or folders

1Check

By default uvicorn watches the current directory and only *.py files. Extra patterns work only when watchfiles is installed (uvicorn[standard] or watchfiles).

docker compose exec web pip show watchfiles

2Fix

Name the folders and patterns to watch.

uvicorn main:app --host 0.0.0.0 --reload --reload-dir /app --reload-include '*.html'

3Verify

Change an .html file and see the reload.

docker compose logs -f web

Confirmed by uvicorn.dev

Did this fix it?

How do I stop it coming back?

  • Keep one dev compose file with the mount and --reload, and a production file with neither.
  • Never run --reload in production images; use fastapi run or uvicorn without it.
  • Install uvicorn[standard] so watchfiles and its include/exclude options are available.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.