Skip to content
Blog

Port Mapping Fundamentals: Publishing Host to Container Ports

Understand Docker port mapping with -p hostPort:containerPort, exposed vs published ports, container networking under iptables NAT, and mapping port ranges.

Published on • November 17, 2026

AI Assistant

By default, Docker containers run in isolated network namespaces. While containers within the same bridge network can communicate with one another using internal container IP addresses, external clients outside the host cannot access services running inside containers unless ports are explicitly published.

This guide covers port mapping fundamentals, the distinction between EXPOSE and publish, port ranges, and how Docker configures host network rules.


1. The -p Flag Syntax: Host to Container Mapping

To expose a container’s internal listening port to the external network, pass the -p or --publish flag during docker run:

docker run -d --name web-server \
  -p 8080:80 \
  nginx:alpine

Understanding the Syntax:

-p <Host_Port>:<Container_Port> [/Protocol]
  • Host_Port (8080): The network port bound on the host machine interface. External clients connect to http://host-ip:8080.
  • Container_Port (80): The port inside the container network namespace where the application daemon (e.g., NGINX) listens.
  • Protocol (Optional): Specifies tcp (default) or udp.

Mapping Specific Protocols (TCP vs UDP)

# Publish port 53 for DNS over UDP
docker run -d --name dns-server \
  -p 53:53/udp \
  coredns/coredns

2. Dynamic Ephemeral Port Allocation with -P

If you want Docker to publish all exposed ports automatically to random available ports on the host system (ephemeral ports between 49152 and 65535), pass the uppercase -P or --publish-all flag:

docker run -d --name dynamic-web -P nginx:alpine

To view the dynamically assigned host port, execute docker port:

docker port dynamic-web

Output:

80/tcp -> 0.0.0.0:32768

3. Exposed Ports vs Published Ports

A common point of confusion for beginners is the difference between EXPOSE in a Dockerfile and publishing ports with -p:

ConceptDeclarationScope & Functionality
Exposed PortEXPOSE 80 in DockerfileDocumentation only. Indicates intended ports; does not make ports accessible to external host networks.
Published Port-p 8080:80 at runtimeActive networking. Creates host iptables NAT rules forwarding host traffic into the container.

Key Rule: An EXPOSE instruction in a Dockerfile does not make a port accessible from outside the host machine unless -p or -P is supplied at runtime.


4. Mapping Port Ranges

For applications that require multiple contiguous ports (such as media streaming servers or FTP data channels), Docker supports binding port ranges:

# Map host ports 8000 through 8010 to container ports 8000 through 8010
docker run -d --name media-streamer \
  -p 8000-8010:8000-8010 \
  streaming-app:latest

Both host and container ranges must contain an equal number of ports.


5. How Docker Handles Port Mapping Under the Hood (iptables NAT)

When you publish a port using -p, the Docker daemon creates Network Address Translation (NAT) rules in the host’s iptables or nftables firewall configuration under the DOCKER chain.

Inspecting Host iptables Rules:

sudo iptables -t nat -L DOCKER -n -v

Output:

DNAT  tcp  --  *  *  0.0.0.0/0  0.0.0.0/0  tcp dpt:8080 to:172.17.0.2:80

Traffic arriving on host port 8080 is intercepted by the Linux kernel’s netfilter subsystem and rewritten (DNAT) to target the internal container IP 172.17.0.2 on port 80.


6. Summary and Best Practices

Takeaway: Enable external network connectivity to containers by publishing host-to-container ports with -p hostPort:containerPort. Remember that EXPOSE serves as image documentation, while -p actively configures kernel iptables NAT rules to route host traffic into container network namespaces.


Sources