You can install Docker on Debian from the distro's own docker.io package or from Docker's official APT repository. On servers and VPS hosts, use Docker's repository — it gives you the current Docker Engine (Docker CE) along with the Compose plugin and Buildx, and a normal apt upgrade keeps all of them updated. If you're new to the platform, start with What is Linux Debian, and for the Ubuntu path read How to Install Docker.
These steps work on Debian 13 Trixie and Debian 12 Bookworm, with notes for anyone still on Debian 11. After the install you'll verify that the Docker daemon runs, set up access without sudo, and fix the errors people hit most often. For deeper learning on containers, see Best Docker Tutorial Sources.
📋 Prerequisites Before You Install Docker on Debian
Supported Debian versions
The Docker Engine install page for Debian lists Debian Trixie 13 (stable) and Debian Bookworm 12 (oldstable). Bookworm is still a fine target — being one release behind only matters when you plan upgrades. Not sure which version you're on? Check your Debian version with a single command first.
| Debian version | Codename | Debian status | Docker Engine notes |
| 13 | Trixie | Stable | Listed in Docker's docs |
| 12 | Bookworm | Oldstable | Listed in Docker's docs |
| 11 | Bullseye | LTS | No longer in Docker's supported list. Upgrade the OS if you can. |
Supported architectures
Docker Engine for Debian is compatible with x86_64 (or amd64), armhf (arm/v7), arm64, and ppc64le (ppc64el). There are no packages for 32-bit i386. Run dpkg --print-architecture to see what your machine reports.
Required permissions and packages
You need root or a sudo user, outbound HTTPS to download.docker.com, and the ca-certificates and curl packages. If the host uses ufw or firewalld, keep Docker's warning in mind before publishing container ports: when you expose container ports using Docker, these ports bypass your firewall rules.
🗑️ Remove Old or Conflicting Docker Packages
Why docker.io and other packages can conflict
Debian ships its own Docker build (docker.io) with separate containerd and runc packages, while Docker's repository bundles containerd and runc into containerd.io. If the Debian copies are installed, apt sees two packages claiming the same files and stops. Removing them leaves your images and volumes under /var/lib/docker in place.
Command to remove old Docker-related packages
for pkg in docker.io docker-doc docker-compose docker-buildx podman-docker containerd runc; do sudo apt-get remove -y $pkg; doneIf apt says a package isn't installed, that's fine.
🐳 Install Docker Engine on Debian Using the Official APT Repository
Update apt and install prerequisites
sudo apt update
sudo apt install -y ca-certificates curlAdd Docker's official GPG key
The key goes in /etc/apt/keyrings, replacing the deprecated apt-key command that older guides use.
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.ascAdd the Docker repository
Current Docker docs use the deb822 .sources format. This command fills in your Debian codename and CPU architecture:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt updateInstall Docker Engine, CLI, containerd, Buildx, and the Compose plugin
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginBuildx is the backend behind docker build and handles multi-platform builds, such as amd64 and arm64 from one command. The Compose plugin adds docker compose. The images you build and pull from here are covered in What is a Docker Image.
Automating with Ansible
For users managing multiple systems, an Ansible playbook automates Docker installation and configuration across servers. Here's a minimal example:
- hosts: all
become: true
tasks:
- name: Update APT and install Docker
apt:
update_cache: yes
name: docker-ce
state: presentDeploy this playbook to automate installation across your Debian servers.
✅ Start and Verify Docker
Enable and start the Docker service
The package usually starts the service during install. This makes sure it's running and starts at boot:
sudo systemctl enable --now dockerCheck the installed version
docker --versionYou should see something like Docker version XX.X.X, build ..., which means the CLI is on your PATH.
Run the hello-world test container
Docker pulls a small image from Docker Hub, runs it, and prints "Hello from Docker!" before the container exits. If you want to understand what just happened, see What is a Docker Container. That message confirms the client, the daemon, and the network path to the registry all work.
sudo docker run hello-worldCheck Docker service status
systemctl status dockerLook for active (running) in green, then press q to exit.
🔓 Run Docker Without Sudo
Add your user to the docker group
The package creates the docker group during install, so just add your user:
sudo usermod -aG docker $USERApply the group change
Log out and back in, or run newgrp docker in your current shell. Then try docker run hello-world without sudo.
Security note about docker group access
Docker's post-install guide says the docker group grants root-level privileges to the user. Anyone in it can mount the host filesystem into a container and edit it as root, so on a shared server, add only people you'd trust with sudo. For a broader checklist, see how to secure a Debian VPS server.
Troubleshooting permissions
If you still get permission errors after adding your user, check group membership with groups $USER. If docker is missing, your session started before the change — log out and back in. If it's there but commands still fail, restart the service with sudo systemctl restart docker.
🎼 Use Docker Compose on Debian
If you're installing Compose separately on another host, see How to Install Docker Compose.
Check the Compose plugin version
docker compose versionCompose v2 came in with the install step as a CLI plugin, so there's no separate binary to download.
Difference between docker compose and docker-compose
docker-compose with a hyphen is the old standalone Compose v1 tool, still common in older tutorials. The plugin uses a space: docker compose up -d. Your docker-compose.yml files work as they are, but scripts and CI jobs that call the hyphenated command need updating.
Basic Compose workflow
docker compose up -d # start services in the background
docker compose ps # check status
docker compose down # stop and remove services📦 Docker Engine vs Docker Desktop on Debian
For a broader comparison of management tools, see Docker vs Portainer, and for container alternatives outside Docker, Docker vs LXC.
| Docker Engine | Docker Desktop | |
| Best for | Servers, VPS, headless hosts, CI runners | Local development on a Debian desktop |
| Interface | CLI only | GUI plus CLI |
| How it runs | Daemon runs directly on the host | Runs Engine inside a VM, so it needs KVM |
| Install docs | Engine on Debian | Desktop on Debian |
On a VPS or dedicated server, install Docker Engine. Docker Desktop fits a Debian laptop with a GNOME or KDE session where you want the GUI. If you also work on other platforms, the install steps for Docker on macOS and Docker on Windows follow the same core commands. Its requirements and license terms differ and are covered in the Docker Desktop for Linux docs.
🚨 Troubleshooting Common Docker Install Errors on Debian
docker: command not found
The install probably didn't finish, often because of a package conflict. Run dpkg -l | grep docker-ce. If nothing comes back, repeat the conflict removal step and the install command.
Permission denied to the Docker daemon socket
The error "permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock" means your user isn't in the docker group, or your session started before you added it. Run groups. If docker is missing, follow the sudo-free steps above and log in again.
GPG key or repository errors
NO_PUBKEY or "repository is not signed" usually means the key file is missing or unreadable. Download it again with curl and run chmod a+r on it. Also look for a leftover docker.list from an older guide: two repo files pointing at the same URL with different Signed-By paths conflict, so delete the old one.
Package not available for your Debian release
"Package 'docker-ce' has no installation candidate" means apt can't find Docker's repository for your release. Usually the codename is wrong (a Debian derivative may report its own), or you skipped apt update after adding the repo. Set the Suites: line in docker.sources to trixie or bookworm and update again.
Service won't start
Run sudo journalctl -u docker --no-pager | tail -50. The usual culprits are a syntax error in /etc/docker/daemon.json or a leftover containerd from the Debian packages.
🗑️ How to Uninstall Docker on Debian
Remove Docker packages
sudo apt purge -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extrasDelete images, containers, and volumes if needed
Warning: the next commands permanently delete every image, container and volume on the host, including any databases stored in volumes. Back up anything you need first.
sudo rm -rf /var/lib/docker /var/lib/containerd
sudo rm /etc/apt/sources.list.d/docker.sources /etc/apt/keyrings/docker.asc🧩 Conclusion
Installing Docker on Debian from the official APT repository gives you the current Docker Engine, the Compose plugin, and Buildx — all updatable with a normal apt upgrade. You now know how to prepare the system, remove conflicting packages, add the repository, verify the install, run Docker without sudo, and uninstall cleanly. To put these containers to work on a reliable, high-performance platform, explore Docker VPS hosting from 1GBits, or spin up a dedicated Debian VPS server for full root access and dedicated resources.
Leave A Comment