Could Not Connect To Docker

Diagnose Docker daemon connection errors on macOS, Linux, and Windows.

Agno uses the Docker Engine SDK for Python to run containers. This error means the SDK cannot reach the Docker daemon:

ERROR    Could not connect to docker. Please confirm docker is installed and running
ERROR    Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

Run this command in the same shell where you run Agno:

docker version

A working connection prints both Client and Server sections. Use the instructions for your Docker installation if the Server section is missing or reports a connection error.

macOS with Docker Desktop

1. Start Docker Desktop and wait for the engine to report that it is running.
2. Open Settings > Advanced.
3. Enable Allow the default Docker socket to be used, then apply the change.
4. Run docker version again.

This setting creates /var/run/docker.sock for SDK clients that use the default socket path. See Docker’s macOS permission requirements and Advanced settings.

If you cannot enable the setting, point the SDK to Docker Desktop’s per-user socket before running Agno:

export DOCKER_HOST="unix://$HOME/.docker/run/docker.sock"

Linux with Docker Desktop

Docker Desktop for Linux uses the desktop-linux context and a per-user socket instead of /var/run/docker.sock.

Start Docker Desktop, then run:

docker context use desktop-linux
export DOCKER_HOST="unix://$HOME/.docker/desktop/docker.sock"
docker version

The context configures the Docker CLI. DOCKER_HOST configures SDK clients such as the one Agno uses. See Using Docker SDKs with Docker Desktop for Linux.

Linux with Docker Engine

Start the Docker daemon:

sudo systemctl start docker
docker version

If sudo docker version succeeds but docker version fails with a permission error, add your user to the docker group:

sudo usermod -aG docker "$USER"

Sign out and back in, then run docker version again. The docker group grants root-level privileges. Review Docker’s Linux post-installation steps before adding users to it.

See Start the daemon for distributions that do not use systemd.

Windows with Docker Desktop

Start Docker Desktop from the Start menu and wait for the engine to report that it is running. Run docker version from the same PowerShell, Command Prompt, or WSL distribution where you run Agno.

Windows clients use the npipe:////./pipe/docker_engine named pipe by default. Do not create a /var/run/docker.sock symlink in PowerShell or Command Prompt. Remove a DOCKER_HOST value that points to a Unix socket, then retry. See Docker’s daemon socket reference.

If you run Agno inside WSL, enable that distribution under Docker Desktop > Settings > Resources > WSL Integration, apply the change, and retry from the WSL shell. See Enable Docker in a WSL 2 distribution.

If Docker Desktop itself does not start, use the Docker Desktop troubleshooting guide.