Uvicorn --reload never restarts when you edit code in a Docker container
The server runs in the container, but saving a file does not print a reload lineShort 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.
Fix it fast
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.py2Match what you see, then jump to its fix
- 1
The two md5sum values differ after you save the fileThe code is copied into the image, not mountedFix - 2
You use develop.watch, and changes never appear inside the containerCompose Watch is not sync-ing, or the image lacks what it needsFix - 3
The files match in both places, but uvicorn prints no reload lineFile-change events do not reach the watcherFix - 4
Python 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
- 1
What does the error look like?
The server runs in the container, but saving a file does not print a reload lineEdits 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:
- ./:/app3Verify
Edit a file, then watch the container log for a reload line.
docker compose logs -f webConfirmed by docs.docker.com
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 watch2Fix
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.txt3Verify
Edit a file under ./app and see it update in the container.
docker compose exec web cat /app/app/main.pyConfirmed by docs.docker.com
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 WATCHFILES2Fix
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 webConfirmed by watchfiles.helpmanual.io
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 watchfiles2Fix
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 webConfirmed by uvicorn.dev
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
Servers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fix