How to Check Established Network Connections in a Docker Container

To list established TCP connections in a running Linux Docker container, run:

docker exec <container> ss -tan state established

Replace <container> with the container name or ID. The command runs ss inside that container’s network namespace, selects TCP sockets, and filters for the established state. It works when ss is installed in the container. For Docker Compose, use docker compose exec <service> ss -tan state established.

This view helps answer whether the container currently has TCP sessions open and shows their local and peer addresses. It is a point-in-time listing, not a history or a complete explanation of application behavior. If the command is unavailable, inspect from an approved diagnostic environment attached to the same network namespace or use a permitted Linux host-side namespace method.

1. What the command shows

ss is the Linux socket inspection utility. Its options here are:

• -t: select TCP sockets.
• -a: include listening and non-listening sockets in the listing; the state filter then narrows the output.
• -n: show numeric addresses and ports instead of resolving names.
• state established: show sockets in the established TCP state.

The ss(8) manual documents filtering by state, including an example for established connections. Numeric output is usually useful for operational checks because it avoids name-service lookups and makes the actual endpoints visible. A typical listing has columns for state, receive and send queue sizes, local address and port, and peer address and port. Exact formatting can vary with the installed iproute2 version.

A line in the output represents a socket, not necessarily one user, request, or application-level transaction. A single process may hold several connections to one peer, and an established connection can be idle. The output does not by itself prove that data is flowing or that an application request succeeded.

2. Run it inside a running container

Find the target container

List running containers and identify the intended instance:

docker ps

Then pass either its name or ID to docker exec:

docker exec api ss -tan state established
# or
 docker exec 2a4c8f2b9d0e ss -tan state established

docker exec starts a command in a running container. It requires an executable command to be present, and it only works while the container’s primary process is running. It does not start a stopped container or install missing diagnostic utilities. These constraints are documented in the Docker CLI reference.

Show process information when available

To ask ss for process details, add -p:

docker exec api ss -tanp state established

Process attribution depends on permissions and the process view available to the command. In a minimal or restricted container, process names or PIDs may be absent even though socket rows are visible. Treat missing process details as a visibility or permission limitation, not proof that no process owns the socket.

Run a filtered query

To focus on a known destination port, use an ss expression. For example, to select established TCP sockets where either endpoint uses port 443:

docker exec api ss -tan state established '( dport = :https or sport = :https )'

Service-name parsing depends on the local service database. Use a numeric port if the name is not recognized:

docker exec api ss -tan state established '( dport = :443 or sport = :443 )'

When adding filters, preserve the state expression and quote the filter as one shell argument. If your shell or ss version rejects the expression, first run the unfiltered established-state command, then check the local ss(8) manual for supported filter syntax.

3. Use Docker Compose

Compose’s exec subcommand runs a command in a running service container. Use the service name from the Compose file:

docker compose exec web ss -tan state established

For process details:

docker compose exec web ss -tanp state established

If the service has multiple replicas, identify the specific container instance you want to inspect. A service-level command may select an instance according to Compose’s behavior and options; it should not be read as a combined list across all replicas. Use docker compose ps to see the service containers, then target the relevant running instance as supported by your Compose version.

4. Choose the right network view

Containers normally have their own network view. Inspect from within the target container or run a diagnostic process in that container’s network namespace. A host-wide ss listing may contain many unrelated host sockets, and published ports or NAT rules do not equal the container’s current established socket list. Docker’s networking overview describes container network configuration and connectivity; the socket listing is a separate runtime view.

Method	Useful when	What to check
docker exec … ss	The image already has ss and you can exec into the container.	Target name or ID, running state, and permissions.
Compose exec	You work with a Compose service.	Service name and which replica is being inspected.
Approved diagnostic container	The application image is minimal and policy allows namespace sharing.	Image provenance, required privileges, and that it joins the target network namespace.
Linux host namespace inspection	You administer the Linux host and have permitted namespace access.	Correct container process PID, namespace handle, host utility availability, and runtime-specific behavior.

docker network inspect <network> is useful for network configuration and topology details. It does not list live established TCP sockets. Use a socket utility for connection state.

5. If ss is missing

Minimal images often omit debugging packages to reduce their contents. Check whether another suitable socket tool is already present, but remember that availability and output syntax vary. Docker does not install tools as a side effect of exec.

Option A: use an approved diagnostic container

An organization-approved diagnostic image can provide socket tools without modifying the application image. It must be attached to the target’s network namespace for the view to match the container’s sockets. The precise Docker options depend on your runtime, deployment policy, and required privileges. Confirm the image source and permissions with your operational policy; do not assume any random diagnostic image is trusted or appropriate.

A diagnostic process that joins only the same Docker network may have network connectivity to peers, but that does not necessarily give it the same network namespace or socket table. The property that matters for listing the target’s sockets is sharing the target network namespace.

Option B: inspect the namespace from a Linux host

Docker’s runtime metrics documentation describes a Linux-host technique that finds a container process PID, accesses its /proc/<pid>/ns/net namespace handle, and invokes a command through ip netns exec. The documented example uses netstat -i; a socket listing can be substituted only if the host has the chosen utility and namespace access is permitted. The exact steps can vary by Docker runtime and Linux distribution, so verify them for the host you administer.

This path requires host-level access and a reliable mapping from the intended container to its host process. Avoid choosing a PID based only on guesswork: verify that it belongs to the target container before inspecting its namespace. If host policy restricts namespace access, use the approved operational method instead.

6. Troubleshooting common errors

Symptom	Likely cause	Fix
executable file not found or ss: not found	ss is not installed in the image or is not on the command path.	Use an available socket utility, an approved diagnostic container in the same namespace, or a permitted host-side method.
Docker says the container is not running	docker exec only runs commands in a running container.	Check docker ps -a and the container’s lifecycle. Start or restore the intended workload through your normal deployment procedure before executing the inspection command.
Output is empty	No matching established TCP sockets existed at that instant, the wrong instance was targeted, or the connection had already closed.	Confirm the container and namespace, repeat while the application is active, and compare with a broader docker exec <container> ss -tan listing.
Only listeners appear	The state filter may have been omitted, misspelled, or interpreted differently by a wrapper.	Run the full command exactly as shown, including state established; consult the installed ss(8) manual if syntax differs.
Host output does not match container output	The host command is viewing the host namespace rather than the container namespace.	Run inside the container or enter its verified network namespace with an approved host procedure.
No process names or PIDs with -p	The command may lack permission or process visibility.	Use an authorized context with sufficient visibility if process attribution is required; the socket rows can still be useful without it.
Compose reports no such service	The service name was confused with a container name, or the command ran from the wrong Compose project directory.	Check the Compose file’s service keys and current project context; use docker compose ps to inspect instances.
Port filter errors	Filter grammar, quoting, or service-name resolution differs.	Start with the unfiltered command, use numeric ports, quote the expression, and check local ss documentation.

7. Interpret results carefully

An established TCP state tells you that the kernel currently considers the connection established. It does not show the application protocol, request contents, ownership in every environment, or whether the remote service is healthy. For a broader diagnosis, correlate the listing with application logs, service metrics, and the peer endpoint.

Because the command samples live state, short-lived connections can open and close between invocations. An empty result is not evidence that the application never connects. Repeat during the relevant workload or use an approved monitoring or tracing approach if you need a timeline. Conversely, a long-lived established socket can remain idle and still appear in the list.

Queue columns are kernel socket queue values, not direct measures of end-to-end latency or total application backlog. Interpret them in context and avoid treating a single snapshot as a performance benchmark. The command is lightweight for an occasional diagnostic, but repeatedly polling many containers at high frequency adds process launches and output volume. For ongoing fleet-wide observability, use the monitoring approach supported by your environment rather than turning manual shell inspection into a polling system.

8. Reliability and operational notes

• Targeting: confirm the container ID or Compose instance before drawing conclusions.
• Namespace: ensure the command sees the target’s network namespace, not merely a network with similar connectivity.
• Timing: record when the command ran and repeat during the symptom, since sockets change quickly.
• Permissions: expect process metadata and host namespace access to vary by user, container configuration, and security controls.
• Repeatability: capture the command and relevant deployment context in incident notes; utility versions can affect columns and filters.
• Cost: the basic workflow uses Docker and the Linux socket utility already available to you. A diagnostic image or monitoring service may have separate operational or licensing costs; check your organization’s approved options. No named performance or price statistics are implied here.

9. Or skip the browser setup

This Docker task is best answered with a socket command in the right network namespace. If your adjacent workflow also needs website captures—for example, documenting an externally visible page—ScreenshotNeo takes a screenshot or PDF with one GET request. Its API is separate from container socket inspection.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account.

10. FAQ

Does this show UDP connections?

No. The -t option selects TCP. UDP does not have TCP’s established connection state; use a suitable UDP socket listing if that is what you need.

Can I see connections for every container with one command?

You can script inspection across containers, but each listing must target the intended container or namespace. Handle stopped containers, missing tools, and replicas explicitly; a host-wide listing is not a substitute for per-container attribution.

Does an established socket prove the remote service is responding?

No. It reports local TCP state at the time of inspection. Application-level health needs an application check or other evidence.

Should I use docker network inspect for this?

Use it for network configuration and topology. For live established sockets, use ss or another socket inspection utility in the right network namespace.

11. Quick checklist

1. Identify the running container or the specific Compose replica.
2. Run ss -tan state established inside its network namespace.
3. Add -p only when process attribution is useful and permitted.
4. If ss is missing, choose an approved diagnostic or host-side namespace method.
5. Repeat during the relevant workload and correlate the snapshot with application evidence.