How to Install Docker on Arch Linux

Install Docker on Arch Linux from the official repositories when you need Docker Engine, the docker CLI, Compose files, and Buildx builds under pacman management. Arch packages Docker as a native systemd service, with containerd and runc pulled in as runtime dependencies.

The setup uses the docker, docker-compose, and docker-buildx packages, starts Docker with either docker.service or docker.socket, fixes the common Docker socket permission error, and shows safe update and removal checks for a rolling Arch system.

Install Docker Engine on Arch Linux

Arch keeps the main Docker stack in the Extra repository. Use the official docker package for Docker Engine, then add docker-compose and docker-buildx when you need the modern Compose and Buildx CLI plugins.

Update Arch Before Installing Docker

Synchronize package metadata and apply pending upgrades before installing Docker:

sudo pacman -Syu

These commands use sudo for tasks that need root privileges. If your user is not in the sudoers file yet, run the commands as root or follow the guide on how to add and manage sudo users on Arch Linux.

Install Docker, Compose, and Buildx

Install Docker Engine with the Compose and Buildx plugins in one pacman transaction:

sudo pacman -S docker docker-compose docker-buildx

Package	What It Provides	Primary Commands
`docker`	Docker Engine daemon, Docker CLI, systemd units, and runtime dependencies such as `containerd` and `runc`.	`docker`, `dockerd`
`docker-compose`	Docker Compose v2 CLI plugin plus the compatibility command for older Compose syntax.	`docker compose`, `docker-compose`
`docker-buildx`	Buildx CLI plugin for BuildKit-backed builds, builder instances, and multi-platform image workflows.	`docker buildx`

This article covers Docker Engine from Arch repositories, not Docker Desktop. Docker Desktop is a separate desktop product that runs Docker inside a Linux VM, uses its own Docker context, and currently ships an experimental Arch package that can conflict with the repository docker-compose and docker-buildx packages. Follow Docker Desktop’s Arch instructions only as a separate install path.

Verify Docker Package Ownership

Confirm the installed commands belong to the expected Arch packages:

pacman -Q docker docker-compose docker-buildx containerd runc
pacman -Qo /usr/bin/docker /usr/bin/docker-compose /usr/lib/docker/cli-plugins/docker-buildx

Relevant output includes the package names and current Arch package versions:

docker 1:29.x.x-1
docker-compose 5.x.x-1
docker-buildx 0.x.x-1
containerd 2.x.x-1
runc 1.x.x-1
/usr/bin/docker is owned by docker 1:29.x.x-1
/usr/bin/docker-compose is owned by docker-compose 5.x.x-1
/usr/lib/docker/cli-plugins/docker-buildx is owned by docker-buildx 0.x.x-1

Arch installs Compose as a Docker CLI plugin under /usr/lib/docker/cli-plugins/ and exposes /usr/bin/docker-compose as a compatibility symlink. Prefer docker compose in new commands, but expect older projects and tutorials to still use docker-compose.

Check Docker Versions

Check the client, Compose plugin, compatibility command, and Buildx plugin:

docker --version
docker compose version
docker-compose --version
docker buildx version

Docker version 29.x.x, build ...
Docker Compose version 5.x.x
Docker Compose version 5.x.x
github.com/docker/buildx 0.x.x ...

The exact versions depend on your mirror state and update timing because Arch is a rolling distribution.

Start Docker with systemd

Docker on Arch uses systemd units from the docker package. Choose the startup behavior before enabling a unit.

Unit	Behavior	Use When
`docker.service`	Starts Docker at boot and keeps the daemon ready.	You run containers often, host services, or want Docker ready immediately after reboot.
`docker.socket`	Listens on the Docker socket and starts the daemon on first use.	You use Docker occasionally on a desktop or development system.

Enable Docker Service Mode

For the normal always-ready setup, enable and start docker.service:

sudo systemctl enable docker.service --now

Verify the service state:

systemctl is-active docker.service
systemctl status docker.service --no-pager

active
● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: disabled)
     Active: active (running) since ...
TriggeredBy: ● docker.socket
   Main PID: ... (dockerd)

Use Socket Activation Instead

If you want Docker to start only when the socket is used, enable docker.socket instead of keeping docker.service enabled at boot:

sudo systemctl disable docker.service --now
sudo systemctl enable docker.socket --now

A Docker command will trigger the service through the active socket:

sudo docker version --format 'Client={{.Client.Version}} Server={{.Server.Version}}'

Client=29.x.x Server=29.x.x

Run Docker Test Containers

Run Docker’s official test image with root privileges first. This confirms the daemon can pull an image, create a container, stream output, and remove the container afterward:

sudo docker run --rm hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.

Then run a small Arch Linux container to verify a normal container command:

sudo docker run --rm archlinux bash -c "echo 'Docker is working on Arch Linux'"

Docker is working on Arch Linux

The --rm flag removes each test container after it exits. Downloaded images remain cached until you remove them with Docker cleanup commands.

Configure Docker User Access

Docker commands require root access by default because the daemon socket is owned by root:docker. Add only trusted users to the docker group, because group members can control a rootful Docker daemon and effectively gain root-equivalent host access.

Add Your User to the Docker Group

Add the current user to the docker group:

sudo usermod -aG docker "$USER"

Start a new login session for the group change to apply everywhere, or activate the group in the current terminal:

newgrp docker

Verify Docker Works Without sudo

Confirm the shell sees the Docker group, then run a non-root Docker command:

groups "$USER"
docker ps

username : username wheel docker
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Rootless Docker is different from adding a user to the rootful Docker group. If you need the daemon and containers to run inside a user namespace, review Docker’s rootless mode documentation and the Arch Wiki’s Docker rootless notes before switching production workloads.

Configure the Docker Daemon

Docker reads daemon settings from /etc/docker/daemon.json. The file is absent on a fresh Arch package install, so create it only when you need host-wide daemon settings. If the file already exists, merge new keys with the existing JSON instead of replacing unrelated settings.

Add Docker Log Rotation

The default json-file logging driver can grow container logs until the host runs out of disk space. Create the configuration directory and edit the daemon file:

sudo install -d -m 0755 /etc/docker
sudo nano /etc/docker/daemon.json

Add or merge the following keys:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Validate the JSON file before restarting Docker:

sudo dockerd --validate --config-file /etc/docker/daemon.json
sudo systemctl restart docker.service

configuration OK

Existing containers keep the logging options they were created with. Recreate a container if you need the new log settings to apply to that container.

Check Docker Storage Driver

Check the active storage driver rather than assuming one from older Docker examples:

docker info --format 'Storage Driver: {{.Driver}}'

Storage Driver: overlayfs

A different filesystem, daemon configuration, or future Docker package can report a different driver. Use the live output when troubleshooting image storage, Btrfs behavior, or volume performance.

Do not expose the Docker API on a remote TCP socket unless you also secure it with SSH or TLS. An unauthenticated Docker API is equivalent to remote root access on the host.

Manage Docker on Arch Linux

Use systemd for the Docker daemon and Docker CLI commands for containers, images, networks, volumes, Compose projects, and Buildx builders.

Use these service commands when you need to start, stop, or reload the daemon after configuration changes:

sudo systemctl start docker.service
sudo systemctl stop docker.service
sudo systemctl restart docker.service

Use these Docker CLI checks to inspect common local objects:

docker ps -a
docker images
docker volume ls

Use these plugin and storage checks when working with Compose, Buildx, or accumulated Docker data:

docker compose up -d
docker buildx ls
docker system df

When you publish container ports with -p or Compose ports:, Docker binds those ports on the host. If you run a host firewall, adjust the matching rules with the Arch guides for Firewalld on Arch Linux or UFW on Arch Linux.

Troubleshoot Docker on Arch Linux

Docker Daemon Is Not Running

If Docker returns this error, the daemon is not running or the socket did not activate it:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Check the unit state and start Docker if needed:

systemctl status docker.service --no-pager
sudo systemctl start docker.service
systemctl is-active docker.service

If the unit fails, inspect the current journal entries:

sudo journalctl -xeu docker.service

Permission Denied on Docker Socket

This permission error means your current shell cannot access the Docker daemon socket:

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

Verify group membership and socket ownership:

groups "$USER"
ls -l /var/run/docker.sock

srw-rw---- 1 root docker 0 ... /var/run/docker.sock

If your user is missing from the docker group, add it and start a fresh login session:

sudo usermod -aG docker "$USER"
newgrp docker
docker ps

Compose or Buildx Command Is Missing

If docker compose, docker-compose, or docker buildx is missing, verify the plugin packages and install the missing one:

pacman -Q docker-compose docker-buildx
sudo pacman -S docker-compose docker-buildx
docker compose version
docker buildx version

Do not install a random AUR or manual binary copy just to fix these commands when the official Arch packages already provide the plugins.

Container Networking or DNS Fails

Start with a bridge-network check and a small BusyBox connectivity test:

sudo docker network ls
sudo docker run --rm busybox ping -c 3 google.com
sudo docker run --rm busybox nslookup google.com

NETWORK ID     NAME      DRIVER    SCOPE
...            bridge    bridge    local
...            host      host      local
...            none      null      local

If DNS fails while raw IP connectivity works, merge a DNS setting into /etc/docker/daemon.json and restart Docker:

{
  "dns": ["1.1.1.1", "8.8.8.8"]
}

sudo dockerd --validate --config-file /etc/docker/daemon.json
sudo systemctl restart docker.service

If all container networking fails, check for VPN or firewall conflicts before changing Docker’s bridge configuration. The Arch Wiki notes that active VPN routes can conflict with Docker bridge and overlay networks.

Docker Uses Too Much Disk Space

Inspect Docker’s disk usage first:

docker system df

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          3         0         571.9MB   571.9MB (99%)
Containers      0         0         0B        0B
Local Volumes   0         0         0B        0B
Build Cache     0         0         0B        0B

Remove stopped containers, unused networks, and dangling images:

docker system prune

Review Docker’s confirmation prompt before continuing. Adding -a removes all unused images, and adding --volumes can remove unused volumes that contain persistent application data.

Update Docker on Arch Linux

Docker, Compose, Buildx, containerd, and runc update through normal Arch package upgrades:

sudo pacman -Syu

After major Docker updates, confirm the daemon and plugins still report correctly:

systemctl is-active docker.service
docker --version
docker compose version
docker buildx version

If you use socket activation, replace the service-state check with systemctl is-active docker.socket or run a Docker command to trigger the daemon.

Remove Docker from Arch Linux

Remove Docker in stages so you can separate package removal from destructive data cleanup.

Stop Docker Units

Stop and disable the Docker service and socket before uninstalling packages:

sudo systemctl disable --now docker.service docker.socket

Stop containerd.service only if this Docker installation is the only workload using containerd:

sudo systemctl disable --now containerd.service

Preview and Remove Docker Packages

Preview the package set pacman would remove:

sudo pacman -Rs docker docker-compose docker-buildx --print

docker-buildx-0.x.x-1
docker-compose-5.x.x-1
docker-1:29.x.x-1
containerd-2.x.x-1
runc-1.x.x-1

If the preview only lists Docker packages and dependencies you no longer need, remove the packages and unused dependencies:

sudo pacman -Rns docker docker-compose docker-buildx

If pacman reports that another installed package depends on Docker, keep Docker installed or remove that dependent package first. Do not use force-removal flags to break package ownership.

Delete Docker Data

The next commands permanently delete Docker images, containers, volumes, custom networks, and daemon configuration. Optional containerd cleanup removes shared runtime state, so run it only after confirming no other container workload uses containerd. Back up needed data first.

Delete Docker’s runtime data and custom daemon configuration:

sudo rm -rf /var/lib/docker
sudo rm -rf /etc/docker

Only remove containerd state if pacman removed the containerd package and you are not using another container runtime that depends on it:

if ! pacman -Q containerd >/dev/null 2>&1; then
  sudo rm -rf /var/lib/containerd
fi

If you added your user to the Docker group only for this installation, remove that membership after Docker is gone:

if groups "$USER" | grep -qw docker; then
  sudo gpasswd -d "$USER" docker
fi

Verify Docker Removal

Confirm the Docker packages are no longer installed:

pacman -Q docker docker-compose docker-buildx

error: package 'docker' was not found
error: package 'docker-compose' was not found
error: package 'docker-buildx' was not found

If containerd or runc still appears in pacman -Q containerd runc, another package may still depend on that runtime component or it may have been installed explicitly.

Docker Resources for Arch Linux

The Arch Wiki Docker page is the best companion source for Arch-specific service, networking, storage, Docker Desktop, and rootless Docker notes. Docker’s own documentation remains the upstream reference for the daemon, CLI, Compose, Buildx, and security model.

Docker Documentation for upstream Docker Engine, CLI, daemon, networking, storage, and security behavior.
Docker Linux post-installation steps for non-root access, systemd startup, and logging-driver guidance.
Docker Compose Documentation for Compose files and multi-container application workflows.
Docker Rootless Mode for running the daemon and containers inside a user namespace.

Conclusion

Docker on Arch Linux works cleanly through the official docker, docker-compose, and docker-buildx packages. Keep the daemon startup choice deliberate, treat Docker group membership as root-equivalent access, validate daemon JSON before restarting, and use pacman for updates so Docker Engine, Compose, Buildx, containerd, and runc stay aligned with the rest of your rolling Arch system.