🦭 Podman Error: 'unable to connect to Podman socket' in Rootless and Docker-Compat Clients

Exact Error Message

$ podman-remote ps
Error: unable to connect to Podman socket: failed to connect: dial unix
/run/user/1000/podman/podman.sock: connect: no such file or directory

Docker-compatible clients pointed at the same socket report it in their own dialect:

$ docker ps
Cannot connect to the Docker daemon at unix:///run/user/1000/podman/podman.sock.
Is the docker daemon running?

What It Means

Unlike Docker, Podman has no always-running daemon. The CLI normally forks the container runtime directly. But anything that speaks the Docker or libpod HTTP API — podman-remote, the docker CLI, docker compose, Testcontainers, the Docker SDKs, IDE plugins — needs a listening API endpoint. Podman provides one through podman system service, which systemd manages as a socket-activated unit. unable to connect to Podman socket means the client resolved a socket path and nothing was listening there, or the socket file existed but the client could not open it.

There are two entirely separate sockets, and confusing them is the most common root cause. The rootless per-user socket lives at $XDG_RUNTIME_DIR/podman/podman.sock (typically /run/user/1000/podman/podman.sock) and is created by the user unit podman.socket, enabled with systemctl --user. The rootful socket lives at /run/podman/podman.sock, is owned by root, and is managed by the system-level podman.socket unit. Containers started via the rootless socket run as your user with user-namespace ID mapping; containers started via the rootful socket run as root. A client configured for one will never see the other’s containers, and if you enable only the system unit while your tooling reads $XDG_RUNTIME_DIR, you get this error even though a Podman API is demonstrably running.

Common Causes

• The podman.socket user unit was never enabled, so nothing listens at $XDG_RUNTIME_DIR/podman/podman.sock.
• DOCKER_HOST or CONTAINER_HOST is unset, so a Docker-compat client falls back to /var/run/docker.sock, which does not exist.
• $XDG_RUNTIME_DIR is unset or wrong in cron jobs, CI runners, and non-login SSH sessions.
• Lingering is disabled, so systemd tears down the user manager — and the socket — the moment the user logs out.
• The client is aimed at the rootful /run/podman/podman.sock but the user is not root and not in a group with access.
• A stale podman system connection entry points at an old socket path or a dead SSH destination.

Diagnostic Commands

Check whether the socket unit is active and where it is listening:

systemctl --user status podman.socket
systemctl --user show podman.socket -p Listen

Confirm the socket file exists and inspect its ownership and mode:

ls -l "$XDG_RUNTIME_DIR/podman/podman.sock"
ls -l /run/podman/podman.sock 2>&1

Ask Podman itself which socket path it considers canonical:

podman info --format '{{.Host.RemoteSocket.Path}}'
podman info --format '{{.Host.RemoteSocket.Exists}}'

List the remote connections Podman has configured and which one is the default:

podman system connection list

Verify the environment your Docker-compat client actually sees:

echo "XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR"
echo "DOCKER_HOST=$DOCKER_HOST"
echo "CONTAINER_HOST=$CONTAINER_HOST"

Step-by-Step Resolution

1. Enable and start the rootless socket for your user. This is the fix for the overwhelming majority of cases:

systemctl --user enable --now podman.socket
systemctl --user status podman.socket

2. Point Docker-compatible tooling at that socket. DOCKER_HOST covers the docker CLI, Compose, and most SDKs; CONTAINER_HOST is what podman-remote reads:

export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"
export CONTAINER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"

Persist it in ~/.bashrc or ~/.config/environment.d/podman.conf so it survives new shells.

3. Enable lingering so the user’s systemd manager — and therefore the socket — stays up without an active login. This is mandatory for service accounts, build agents, and anything driven over SSH:

sudo loginctl enable-linger "$USER"
loginctl show-user "$USER" --property=Linger

4. If you genuinely need the rootful socket (privileged ports, host networking, system-wide containers), enable the system unit and grant access deliberately rather than loosening permissions on the file:

sudo systemctl enable --now podman.socket
sudo ls -l /run/podman/podman.sock
export DOCKER_HOST="unix:///run/podman/podman.sock"

5. Repair or recreate the Podman connection entry if podman system connection list shows a stale target:

podman system connection remove default
podman system connection add --default rootless \
  "unix://$XDG_RUNTIME_DIR/podman/podman.sock"
podman system connection list

6. Verify end to end with both the native and the compatibility API:

podman --remote info --format '{{.Host.Arch}}'
curl -s --unix-socket "$XDG_RUNTIME_DIR/podman/podman.sock" \
  http://d/v1.41/version

Testcontainers and similar libraries additionally require TESTCONTAINERS_RYUK_DISABLED=true on many rootless setups, since the reaper container expects to bind the Docker socket into itself. If your containers then fail to reach the network at all, check Podman error: netavark IO error, which covers the rootless networking state that lives beside the socket in $XDG_RUNTIME_DIR.

Prevention

• Enable podman.socket and loginctl enable-linger as part of provisioning any host that runs rootless workloads.
• Export DOCKER_HOST from ~/.config/environment.d/ rather than an interactive shell rc, so systemd user units inherit it too.
• Never chmod 666 the socket — it is a full container-control API; use the rootless per-user socket instead of sharing a rootful one.
• Set XDG_RUNTIME_DIR explicitly in cron and CI job definitions, where it is routinely absent.
• Keep one canonical podman system connection per host and remove stale entries when machines are rebuilt.
• Prefer podman --remote over the docker shim in scripts you own, so failures name the real socket path.

Related Errors

• Cannot connect to the Docker daemon at unix:///var/run/docker.sock — the client never picked up DOCKER_HOST and used the Docker default path.
• permission denied on /run/podman/podman.sock — you reached the rootful socket as an unprivileged user; use the rootless one.
• Error: unable to connect to Podman socket: ... connection refused — the socket file exists but the service failed to start; check systemctl --user status podman.service.
• Failed to start podman.service: Unit not found — the podman package on that distro ships the API service separately; install the full package set.

Frequently Asked Questions

Do I need a Podman daemon running all the time? No. podman.socket is socket-activated: systemd holds the listening socket and only starts podman.service when a client connects, then lets it exit after an idle timeout. You get daemon-like API access without a persistent daemon.

Why does the socket disappear when I log out? Without lingering, systemd stops the user manager at logout and removes /run/user/<uid> along with everything in it. sudo loginctl enable-linger <user> keeps the user manager — and the socket — alive across logins and reboots.

Should I use the rootless or the rootful socket? Use rootless unless you have a concrete need for root-owned containers. Rootless containers run under your UID with user-namespace mapping and are far safer to expose to CI tooling. Mixing the two is why docker ps sometimes shows an empty list while podman ps shows containers.

Why does Docker Compose still fail after I set DOCKER_HOST? Compose spawns helpers that may not inherit an interactive-shell export, and some versions require the socket to be reachable at container start too. Set the variable in ~/.config/environment.d/podman.conf and re-login. For more rootless container fixes, see the Podman guides.