Maaz Zindani

Loading the index…

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

Flask app runs in Docker but http://127.0.0.1:5000 will not open

ErrorThis site can't be reached. 127.0.0.1 refused to connect.

Short answer

Flask listens on 127.0.0.1 by default, which inside a container means only the container itself. Start it with --host=0.0.0.0, and publish the port with -p 5000:5000. On a Mac, port 5000 may also be taken by the AirPlay Receiver, so map another host port.

  • Applies to Flask 3.1, Docker Engine 28, Python 3.13
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at the container's own log and at the port column. The log shows the address Flask bound to, and docker ps shows whether any host port is mapped.

    docker logs my-flask
    docker ps --format '{{.Names}} {{.Ports}}'
  2. 2Match what you see, then jump to its fix

    1. 1The log says Running on http://127.0.0.1:5000, and the PORTS column may already show 5000->5000Flask is bound to 127.0.0.1 inside the containerFix
    2. 2docker ps shows 5000/tcp with no arrow and no host portThe port is not published to the hostFix
    3. 3docker run fails to bind, or you reach a different service on 5000; on macOS Monterey and later this is often the AirPlay ReceiverPort 5000 on the host is already used by another programFix

What does the error look like?

  • This site can't be reached. 127.0.0.1 refused to connect.
  • Running on http://127.0.0.1:5000

Cause 1 of 3

Flask is bound to 127.0.0.1 inside the container

1Check

The Flask quickstart says the development server is reachable only from the same computer by default. In a container, that computer is the container, so traffic arriving from the host is not accepted.

docker logs my-flask 2>&1 | grep -i running

2Fix

Start Flask with --host=0.0.0.0 so it listens on all addresses. Flask's docs say to do this only when the debugger is off or you trust the network.

# Dockerfile
CMD ["flask", "--app", "app", "run", "--host=0.0.0.0"]

3Verify

Rebuild and run, then request the page from the host.

docker build -t my-flask .
docker run -d --name my-flask -p 5000:5000 my-flask
curl -I http://127.0.0.1:5000

Confirmed by flask.palletsprojects.com

Did this fix it?

Cause 2 of 3

The port is not published to the host

1Check

Containers are isolated, so you cannot reach one from the host until a port is published. The format is host port first, then container port.

docker ps --format '{{.Names}} {{.Ports}}'

2Fix

Recreate the container with -p HOST:CONTAINER. In Compose, put the same pair under ports. Add 127.0.0.1: in front to keep it local to your machine.

docker run -d --name my-flask -p 127.0.0.1:5000:5000 my-flask

# compose.yaml
services:
  web:
    build: .
    ports:
      - "127.0.0.1:5000:5000"

3Verify

The PORTS column now shows the mapping.

docker ps --format '{{.Names}} {{.Ports}}'

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Port 5000 on the host is already used by another program

1Check

The Flask docs say macOS Monterey and later starts a service that uses port 5000. They show lsof for finding the process on macOS and Linux.

lsof -P -i :5000

2Fix

Publish the container on a different host port, or switch off AirPlay Receiver in System Settings.

docker run -d --name my-flask -p 5001:5000 my-flask

3Verify

Open the new host port.

curl -I http://127.0.0.1:5001

Confirmed by flask.palletsprojects.com

Did this fix it?

How do I stop it coming back?

  • Put the host and port flags in the Dockerfile CMD so every run starts the same way.
  • Use Gunicorn or another production server for anything public; the Flask dev server is for local work only.
  • Write the ports pair in compose.yaml so the mapping is in version control.

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.