How to Install Docker on Arch Linux

Docker on Arch Linux lets you run applications in isolated containers that bundle code, libraries, and dependencies together. Whether you need to spin up a disposable database for testing, run CI/CD pipelines locally, develop in clean environments without cluttering your host system, or deploy consistent images across development and production, Docker provides the foundation for container-based workflows.

This guide walks through installing Docker Engine from the official Arch Linux repositories, enabling the Docker daemon, configuring non-root user access, and verifying everything works with test containers. You will also install Docker Compose for multi-container applications and Buildx for advanced image building. By the end, you will have a fully functional Docker environment ready for development or production workloads. If you need to configure sudo privileges for Docker users on Arch Linux, complete that first to ensure proper access control.

Install Docker on Arch Linux

Docker is available in the official Arch Linux repositories, making installation straightforward with pacman. The docker package provides the Docker Engine daemon, CLI client, and container runtime.

Update System First

Synchronize the package database and upgrade existing packages to prevent dependency conflicts:

sudo pacman -Syu

Install Docker Engine

Install Docker using pacman:

sudo pacman -S docker

This installs the Docker Engine daemon (dockerd) and the Docker CLI client (docker). Pacman automatically pulls in containerd and runc as dependencies since Docker uses them as the container runtime.

Install Docker Compose

Docker Compose defines and runs multi-container applications using YAML configuration files. Install it as a separate package:

sudo pacman -S docker-compose

Arch Linux installs Compose as a Docker CLI plugin in /usr/lib/docker/cli-plugins/ and creates a compatibility symlink at /usr/bin/docker-compose. This means both docker compose (plugin syntax) and docker-compose (standalone syntax) work identically.

Install Docker Buildx

Docker Buildx extends build capabilities with multi-platform builds and advanced caching. Install it as a CLI plugin:

sudo pacman -S docker-buildx

After installation, Buildx integrates with the Docker CLI as docker buildx.

Verify Installation

Confirm Docker and its components are installed:

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

Example output:

Docker version 29.2.0, build 0b9d1985db
Docker Compose version 5.0.2
github.com/docker/buildx 0.31.0 44945d71ff077ce7fc142fbdee6acec8d9acb630

Your version numbers will reflect the current Arch Linux packages. Since Arch uses a rolling release model, you always receive the latest stable Docker release through regular system updates.

Start and Enable the Docker Service

The Docker daemon runs as a systemd service. You can choose between two unit files depending on your startup preference.

Choose Your Startup Method

Unit	Behavior	Best For
docker.service	Starts Docker daemon at boot	Servers and systems that always need Docker available
docker.socket	Starts Docker daemon on first use	Desktops where Docker is used occasionally

For most users, docker.service provides the expected behavior where Docker is always ready after boot.

Enable and Start Docker Service

Enable the Docker service to start automatically at boot and start it immediately:

sudo systemctl enable docker --now

The --now flag combines enabling and starting into a single command.

Verify Docker Service Status

Check that the Docker daemon is running:

systemctl status docker

Expected output showing active status:

● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: disabled)
     Active: active (running) since [date]; [duration] ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: [pid] (dockerd)
      Tasks: 10
     Memory: 28.5M
        CPU: 245ms
     CGroup: /system.slice/docker.service
             └─[pid] /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

[date] archlinux dockerd[[pid]]: time="[timestamp]" level=info msg="API listen on /run/docker.sock"
[date] archlinux systemd[1]: Started Docker Application Container Engine.

The output confirms Docker is running and listening on its Unix socket.

Alternative: Socket Activation

If you prefer Docker to start only when first accessed rather than at boot, enable the socket unit instead:

sudo systemctl enable docker.socket --now

With socket activation, the first Docker command triggers the daemon to start, reducing boot time on systems where Docker is not always needed.

Run a Test Container

Verify Docker works by running the official hello-world container:

sudo docker run --rm hello-world

Successful output:

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
e6590344b1a5: Pull complete
Digest: sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Status: Downloaded newer image for hello-world:latest

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

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

The --rm flag automatically removes the container after it exits, keeping your system clean.

For a more comprehensive test using an Arch Linux container:

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

Unable to find image 'archlinux:latest' locally
latest: Pulling from library/archlinux
[...]
Status: Downloaded newer image for archlinux:latest
Docker is working on Arch Linux

Configure Non-Root User Access

By default, Docker commands require root privileges. Adding your user to the docker group allows running Docker without sudo.

Add User to Docker Group

Add your current user to the docker group:

sudo usermod -aG docker $USER

The Docker group grants root-equivalent privileges through the Docker daemon socket. Members can run containers with full host access, mount any directory, and effectively bypass normal permission restrictions. Only add trusted users to this group. For production environments requiring stricter isolation, consider rootless Docker mode.

Activate Group Membership

Group changes require a new login session. You have two options:

Option 1: Activate the group immediately in the current terminal:

newgrp docker

This starts a new shell with the docker group active.

Option 2: Log out and log back in to apply the group membership system-wide.

Verify Non-Root Access

Test that Docker commands work without sudo:

docker ps

Expected output showing an empty container list:

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

If you see a permission error, verify your group membership with groups $USER and ensure docker appears in the list.

Docker Configuration

Docker reads configuration from /etc/docker/daemon.json. This file does not exist by default; create it to customize Docker behavior.

Configure Log Rotation

Docker’s default logging driver stores container logs without size limits, which can exhaust disk space over time. Configure log rotation to prevent this:

sudo nano /etc/docker/daemon.json

Add the following configuration:

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

This limits each container’s log file to 10 megabytes and keeps a maximum of 3 rotated files. Adjust these values based on your storage capacity.

Apply the configuration by restarting Docker:

sudo systemctl restart docker

Existing containers retain their original logging settings. Only containers created after this change will use log rotation.

Storage Driver

Docker on Arch Linux uses the overlay2 storage driver by default, which provides good performance for most use cases. You can verify the active storage driver with:

docker info | grep "Storage Driver"

 Storage Driver: overlay2

The overlay2 driver works with ext4 and xfs filesystems. If your /var/lib/docker directory uses Btrfs, Docker automatically selects the btrfs storage driver instead.

If you run Docker on Btrfs and use volumes for database containers (MySQL, PostgreSQL, MongoDB), consider disabling Copy-on-Write for the volume directories to avoid performance issues. The Arch Linux package handles this automatically for /var/lib/docker via systemd-tmpfiles, but manually created volume paths may need chattr +C before storing data.

Managing Docker with systemd

Use these systemctl commands to manage the Docker service:

sudo systemctl start docker

Starts the Docker daemon immediately.

sudo systemctl stop docker

Stops the Docker daemon. Running containers will be stopped.

sudo systemctl restart docker

Restarts the Docker daemon. Use this after configuration changes.

sudo systemctl enable docker

Enables Docker to start automatically at boot.

sudo systemctl disable docker

Disables automatic startup. Docker remains available for manual start.

Docker Command Reference

These commands cover common Docker operations for managing containers, images, networks, and volumes:

Command	Description
docker run	Create and start a container from an image
docker ps	List running containers (-a for all)
docker images	List downloaded images
docker build	Build an image from a Dockerfile
docker stop	Stop a running container
docker rm	Remove a stopped container
docker rmi	Remove an image
docker network ls	List Docker networks
docker volume ls	List Docker volumes
docker logs	View container logs
docker exec	Run a command in a running container
docker pull	Download an image from a registry
docker push	Upload an image to a registry
docker info	Display system-wide Docker information
docker system prune	Remove unused containers, images, and networks

Run an Interactive Container

Start a container with an interactive shell:

docker run -it archlinux bash

The -i flag keeps stdin open and -t allocates a pseudo-terminal. Type exit to leave the container.

Run a Detached Container

Start a container in the background:

docker run -d --name webserver -p 8080:80 nginx

This runs an Nginx container named “webserver” in detached mode, mapping port 8080 on the host to port 80 in the container.

Clean Up Unused Resources

Remove stopped containers, unused networks, and dangling images to free disk space:

docker system prune

Add -a to also remove unused images (not just dangling ones), and --volumes to include unused volumes.

Troubleshooting Common Issues

These are the most frequently encountered problems when running Docker on Arch Linux.

Cannot Connect to Docker Daemon

If Docker commands fail with an error like this:

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

The Docker service is not running. Check the service status:

systemctl status docker

If the service is inactive, start it:

sudo systemctl start docker

If the service fails to start, check the journal for errors:

sudo journalctl -xeu docker

Permission Denied on Docker Socket

The error “permission denied while trying to connect to the Docker daemon socket” means your user is not in the docker group.

Verify your group membership:

groups $USER

Look for docker in the output:

username : username wheel docker

If docker is not listed, add your user to the group:

sudo usermod -aG docker $USER
newgrp docker

Verify the socket permissions:

ls -l /var/run/docker.sock

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

The socket should be owned by root:docker with group read-write permissions.

Container Networking Issues

If containers cannot reach external networks, verify the default bridge network exists:

docker network ls

NETWORK ID     NAME      DRIVER    SCOPE
e0f4b42f45f7   bridge    bridge    local
2b92e331d2c7   host      host      local
359d4c681ec9   none      null      local

Test container networking:

docker run --rm busybox ping -c 3 google.com

If networking fails, ensure IP forwarding is enabled:

cat /proc/sys/net/ipv4/ip_forward

If it returns 0, enable IP forwarding:

sudo sysctl -w net.ipv4.ip_forward=1

To make this persistent across reboots, add it to sysctl configuration:

echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-docker.conf
sudo sysctl --system

DNS Resolution Fails Inside Containers

If containers can ping IP addresses but not resolve hostnames, Docker’s default DNS configuration may conflict with your local setup. This often happens when the host uses systemd-resolved or a local DNS resolver.

Test DNS resolution inside a container:

docker run --rm busybox nslookup google.com

If this fails while ping 8.8.8.8 succeeds, configure Docker to use public DNS servers. Add a DNS setting to /etc/docker/daemon.json:

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

Restart Docker to apply the change:

sudo systemctl restart docker

Disk Space Issues

Docker stores images, containers, and volumes in /var/lib/docker. If you run low on disk space, check Docker’s disk usage:

docker system df

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          5         2         1.2GB     800MB (66%)
Containers      3         1         50MB      30MB (60%)
Local Volumes   2         1         100MB     50MB (50%)
Build Cache     10        0         500MB     500MB

Reclaim unused space:

docker system prune -a --volumes

The --volumes flag also removes unused volumes, which may contain persistent data. Review what will be removed before confirming.

Remove Docker from Arch Linux

When you no longer need Docker, remove it completely to free disk space and eliminate the attack surface.

Stop and Disable Docker Service

Stop the running Docker daemon and disable automatic startup:

sudo systemctl stop docker
sudo systemctl disable docker

Remove Docker Packages

Remove Docker and its related packages with complete cleanup:

sudo pacman -Rns docker docker-compose docker-buildx

The -Rns flags perform a complete removal: -R removes the packages, -n deletes configuration files, and -s removes orphaned dependencies.

Remove Docker Data

The following commands permanently delete all Docker images, containers, volumes, and custom networks. This action cannot be undone. Back up any important container data before proceeding.

Delete Docker’s data directories:

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

Remove Docker configuration:

sudo rm -rf /etc/docker

Verify Removal

Confirm Docker is no longer installed:

pacman -Qi docker

Expected output:

error: package 'docker' was not found

Common Questions

Additional Resources

For comprehensive Docker documentation specific to Arch Linux, consult the Arch Wiki Docker page. The Arch Wiki covers advanced topics including network configuration, GPU passthrough, and troubleshooting distribution-specific issues.

If you plan to manage Docker hosts remotely or expose container services over SSH, see the guide to install and configure OpenSSH on Arch Linux for secure remote access.

Additional resources for Docker usage and best practices:

• Docker Documentation: Official guides for all Docker features and configuration options.
• Docker Compose Documentation: Define and run multi-container applications.
• Docker Security: Best practices for securing Docker deployments.
• Rootless Mode: Run Docker without root privileges for improved security.

Conclusion

You now have a working Docker environment on Arch Linux with the daemon running, non-root access configured, and both Compose and Buildx available for multi-container applications and advanced builds. Since Arch uses a rolling release model, Docker updates arrive automatically through regular system upgrades with sudo pacman -Syu. For production deployments, configure log rotation to prevent disk exhaustion, and consider rootless mode if you need stronger isolation between container workloads and the host system.