Python requests fails with Errno 111 Connection refused between Compose services
Max retries exceeded with urlShort answer
Errno 111 means nothing accepted the connection at that address. Between Compose services the usual reasons are calling localhost or the published host port instead of the service name and container port, a server bound to 127.0.0.1 inside its container, or a caller that starts before the server is ready.
Fix it fast
1Find out which cause you have
From inside the calling container, try the exact URL your code uses. If it fails there too, the URL or the target is wrong, not requests.
docker compose exec web python -c "import urllib.request as u; print(u.urlopen('http://api:8000/').status)"2Match what you see, then jump to its fix
- 1
The URL is http://localhost:PORT or names the left-hand number of a HOST:CONTAINER port mappingThe URL uses localhost or the published host portFix - 2
The service answers from inside its own container but refuses other containersThe server listens only on 127.0.0.1 inside its own containerFix - 3
The error appears at startup and goes away if you restart the caller laterThe caller started before the server was readyFix
- 1
What does the error look like?
Max retries exceeded with urlFailed to establish a new connection: [Errno 111] Connection refused
Cause 1 of 3
The URL uses localhost or the published host port
1Check
Containers on one Compose network reach each other by service name, and traffic between them uses the container port, the right-hand number. The host port only matters from outside the network.
grep -n -B2 -A4 "ports:" docker-compose.yml
grep -R -n "http://localhost" --include=*.py .2Fix
Call the service name and the container port. Keep the value in an environment variable.
# docker-compose.yml: api publishes "8001:8000"
# inside the web container, use the service name and port 8000
API_URL=http://api:80003Verify
Run the request again from the calling container.
docker compose exec web python -c "import os, requests; print(requests.get(os.environ['API_URL']).status_code)"Confirmed by docs.docker.com
Cause 2 of 3
The server listens only on 127.0.0.1 inside its own container
1Check
Django runserver binds 127.0.0.1:8000 unless told otherwise, and so does Gunicorn. 127.0.0.1 in a container is that container only. Other containers cannot reach it.
docker compose exec api sh -c 'ss -ltn || netstat -ltn'2Fix
Bind to all interfaces in the container.
python manage.py runserver 0.0.0.0:8000
# or, with Gunicorn
gunicorn --bind 0.0.0.0:8000 myproject.wsgi:application3Verify
Repeat the request from the other container.
docker compose exec web python -c "import requests; print(requests.get('http://api:8000/').status_code)"Confirmed by docs.djangoproject.com
Cause 3 of 3
The caller started before the server was ready
1Check
Compose starts services in dependency order, but a container being started is not the same as a server accepting connections. Without a health check, depends_on cannot wait for readiness.
docker compose ps2Fix
Add a health check to the server and make the caller wait for it to be healthy.
services:
web:
build: .
depends_on:
api:
condition: service_healthy
api:
build: ./api
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request as u; u.urlopen('http://localhost:8000/')"]
interval: 10s
retries: 5
start_period: 30s3Verify
Bring the stack up from scratch and watch web start after api is healthy.
docker compose down && docker compose upConfirmed by docs.docker.com
How do I stop it coming back?
- Put service URLs in environment variables and use the Compose service name in them.
- Always bind servers in containers to 0.0.0.0.
- Add a health check to every service other services depend on.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Databases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixServers
Reaching a service on the host's localhost from inside a Docker container
getaddrinfo ENOTFOUND host.docker.internal
Inside a container, localhost is the container itself, not your machine.
5 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
pip install cryptography tries to compile and fails in a Docker build
fatal error: 'openssl/aes.h' file not found
cryptography ships prebuilt wheels.
3 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
Docker cannot find manage.py or Permission denied on '/manage.py'
PermissionError: [Errno 13] Permission denied: '/manage.py'
The container is looking for manage.py in a directory where the file is not.
3 causes, each with a fix