Docker packages applications and their dependencies into isolated containers that run consistently across development, testing, and production environments. Unlike virtual machines, Docker containers share the host kernel, making them lightweight and fast to start while maintaining strong isolation between applications.
This guide walks through installing Docker Engine on Ubuntu using the official Docker APT repository. By the end, you will have a working Docker installation with systemd service management, non-root user access configured, and the ability to build, run, and manage containers on your Ubuntu system.
System Requirements
Docker supports multiple Ubuntu versions across different architectures. Ensure your system meets the following requirements before proceeding with installation:
| Ubuntu Version | Release Name | Supported Architectures |
|---|---|---|
| Ubuntu 25.10 | Questing Quokka | x86_64/amd64, arm64, armhf, s390x, ppc64le |
| Ubuntu 25.04 | Plucky Puffin | x86_64/amd64, arm64, armhf, s390x, ppc64le |
| Ubuntu 24.04 LTS | Noble Numbat | x86_64/amd64, arm64, armhf, s390x, ppc64le |
| Ubuntu 22.04 LTS | Jammy Jellyfish | x86_64/amd64, arm64, armhf, s390x, ppc64le |
Docker requires a 64-bit version of Ubuntu with a kernel version of 3.10 or higher. LTS releases receive Docker support for their entire five-year support period, while non-LTS releases receive support for nine months following the Ubuntu release schedule.
Choose Your Docker Installation Method
Docker offers multiple installation methods on Ubuntu. This guide covers the recommended APT repository method, which provides automatic security updates through standard system upgrades and follows best practices for package management.
If you use ufw or firewalld on Ubuntu, be aware that Docker modifies iptables rules directly, which may conflict with firewall configurations. These firewalls do not forward traffic to and from Docker containers by default, potentially causing connectivity issues. Review your firewall rules and Docker networking requirements before proceeding.
Remove Previous Docker Installations
Before installing Docker on Ubuntu, check whether Docker is already installed on your system by running:
docker --versionIf Docker is installed, this command displays the version number. If not, you’ll see a “command not found” message.
Before proceeding with installation, it’s important to remove any previous Docker installations to avoid conflicts. Additionally, these steps ensure a clean environment for your new Docker setup.
First, run the following command to eliminate these older versions:
sudo apt remove docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runcIf you have not installed any of these packages, apt will send a message indicating nothing to remove.
The following commands will permanently delete all Docker images, containers, volumes, and networks stored in
/var/lib/docker/and/var/lib/containerd/. Only run these if you want a completely clean Docker installation.
Uninstalling Docker does not automatically remove images, containers, volumes, and networks stored in /var/lib/docker/. To start with a clean installation and delete all existing data, use the following commands:
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerdIf you’re performing a complete uninstallation, remove the Docker repository and keyring to prevent package manager issues:
sudo rm /etc/apt/sources.list.d/docker.sources
sudo rm /etc/apt/keyrings/docker.ascAfter removing any older versions of Docker, you should update your system to ensure that all packages are up-to-date and avoid potential conflicts. You can do this by running the following command:
sudo apt update && sudo apt upgradeThis command updates the list of available packages and upgrades any ones that need updating.
Add Docker Repository to Ubuntu
Before installing Docker, import the Docker repository and GPG key into your system. This ensures that your system can verify the downloaded packages from the repository and prevent unauthorized changes.
To begin, install the required packages for downloading and verifying the Docker repository:
sudo apt install ca-certificates curlCreate the keyrings directory if it doesn’t exist:
sudo install -m 0755 -d /etc/apt/keyringsNext, download Docker’s official GPG key:
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.ascThis downloads the GPG key and sets appropriate read permissions for package verification.
Add the Docker repository using the modern DEB822 format:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOFThis creates a repository configuration file that automatically detects your Ubuntu version and points to Docker’s official package repository.
After importing the repository, refresh your package index so APT reads metadata from download.docker.com:
sudo apt updateOnce the cache is updated, verify that APT installs Docker from the official repository rather than the Ubuntu default repository:
apt-cache policy docker-ceThis displays the available Docker versions and their sources. The output should show the Docker repository URL (download.docker.com) with a higher priority than any Ubuntu repository entries, confirming your system will install from the correct source.
Example output:
docker-ce:
Installed: (none)
Candidate: 5:27.4.0-1~ubuntu.24.04~noble
Version table:
5:27.4.0-1~ubuntu.24.04~noble 500
500 https://download.docker.com/linux/ubuntu noble/stable amd64 Packages
Install Docker on Ubuntu
Now you’re ready to install Docker on Ubuntu using the official Docker repository. This section covers the commands and steps required to install Docker efficiently and securely.
Update your system before installing Docker to ensure your source lists accurately reflect the newly imported repository. Run the following command to do this:
sudo apt updateOnce your system is up-to-date, you can install Docker using the following command:
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginThis command installs Docker and some additional plugins that you may find helpful.
After installing Docker, verify the installation by checking the service status and version:
sudo systemctl status dockerThis displays detailed information about the Docker service, including whether it’s active and running. You should see output similar to:
● docker.service - Docker Application Container Engine
Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
Active: active (running) since Fri 2025-11-08 14:23:15 UTC; 2min ago
TriggeredBy: ● docker.socket
Docs: https://docs.docker.com
Main PID: 12345 (dockerd)
Tasks: 8
Memory: 42.1M
CPU: 385ms
CGroup: /system.slice/docker.service
└─12345 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
The “active (running)” status confirms Docker is operating correctly. Additionally, verify the installed version:
docker --versionYou should see output similar to:
Docker version 27.4.1, build b9d17ea
After installing Docker, verify the installation by running a test container. This helps confirm that Docker is set up correctly on your Ubuntu system:
sudo docker run hello-worldA successful test displays output similar to:
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. 4. The Docker daemon streamed that output to the Docker client.
The docker command requires root privileges by default. The next section covers configuring non-root user access, which provides a more secure way to manage containers.
If you experience problems with Docker images or path generation, a system reboot often resolves these issues:
sudo rebootManaging Docker with systemd on Ubuntu
Systemd, a system and service manager, simplifies Ubuntu’s process and service management. Upon Docker installation on Ubuntu, it establishes a systemd unit to oversee the Docker service. Consequently, systemd commands can control this unit, offering a convenient method for starting, stopping, and managing Docker containers and images.
Below are some frequently used systemd commands for Docker management on Ubuntu:
sudo systemctl start docker.serviceThis starts the Docker service immediately for the current session. Use the enable command below if you want it to start automatically at boot.
sudo systemctl stop docker.serviceThis stops the Docker service until you start it again or reboot. It does not change whether Docker auto-starts on boot.
sudo systemctl restart docker.serviceRestarts the Docker service.
sudo systemctl status docker.serviceDisplays the current status of the Docker service.
sudo systemctl enable docker.serviceEnables the Docker service to start automatically on system boot. Docker installs with this enabled by default, but use this command if you previously disabled auto-start.
sudo systemctl disable docker.serviceDisables automatic startup of the Docker service on system boot. The service remains available for manual start with systemctl start docker.service, but won’t launch during boot.
Docker Configuration and Usage
Manage Docker as a non-root user on Ubuntu
When running Docker, avoid using the root user to prevent security risks and accidental changes to the host system. Instead, manage Docker as a non-root user by adding users to the Docker group.
If you want to add a new user for Docker management, use the following command:
sudo useradd -m dockeruserIf the user already exists, skip this step.
Alternatively, to add an existing user (such as your current user) to the Docker group, use:
sudo usermod -aG docker usernameThe Docker group grants root-equivalent privileges to users. Members can access the Docker daemon socket, which provides full control over the host system. Only add trusted users to this group, as they can escape container isolation and modify host files. For production environments, consider using rootless Docker mode or implementing proper access controls.
Replace username above with the account you actually use on the Ubuntu system so you add the correct user to the Docker group.
After adding a user to the Docker group, you have two options to activate the group membership:
Option 1: Activate immediately without logging out using the newgrp command:
newgrp dockerThis starts a new shell session with the docker group active, allowing you to run Docker commands immediately.
Option 2: Log out and back in, or reboot your system for the changes to take effect system-wide.
To ensure the user can run Docker commands, use the following command:
docker psIf Docker is working correctly with your user account, you should see an empty container list:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMESThis confirms Docker commands run without sudo. If you see a permission error instead, verify the group membership activated correctly or try logging out and back in.
If you encounter permission errors when running Docker commands (such as errors accessing ~/.docker/config.json), fix the ownership and permissions on the Docker configuration directory:
sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
sudo chmod -R g+rwx "$HOME/.docker"These commands set the correct ownership and permissions for your user’s Docker configuration directory, resolving common permission-related issues.
Configure Log Rotation
By default, Docker logs to the JSON file format without size limits. This can consume unlimited disk space over time.
Docker’s default json-file logging driver does not limit log file size or implement automatic rotation. Without proper configuration, containers can consume unlimited disk space through logging, potentially filling your filesystem. Always configure log rotation with
max-sizeandmax-fileoptions in production environments to prevent disk exhaustion.
To configure log rotation, create the Docker daemon configuration file:
sudo nano /etc/docker/daemon.jsonAdd the following configuration to limit log file size and count:
{
"log-driver": "json-file",
"log-opts": {
"max-size": "10m",
"max-file": "3"
}
}This configuration limits each container’s log file to 10 megabytes and keeps a maximum of 3 rotated log files. Adjust these values based on your storage capacity and logging requirements.
After creating the file, restart the Docker daemon to apply the changes:
sudo systemctl restart docker.serviceExisting containers retain their original logging configuration. Only containers created after this change will use the new log rotation settings.
Docker Command Reference
The following table summarizes commonly used Docker commands for managing containers, images, networks, and volumes:
| Command | Description |
|---|---|
docker run | Run a new container from an image. |
docker ps | List all running containers. |
docker images | List all available images. |
docker build | Build a new image from a Dockerfile. |
docker stop | Stop a running container. |
docker rm | Remove a container. |
docker rmi | Remove an image. |
docker network | Manage Docker networks. |
docker volume | Manage Docker volumes. |
docker info | Display system-wide Docker information. |
docker search | Search Docker Hub for images. |
View Docker System Information
The docker info command displays comprehensive system-wide information about your Docker installation, including the number of containers and images, storage driver details, and system resources.
docker infoThis displays detailed information about your Docker environment, helping you verify configuration and troubleshoot issues. The output includes container and image counts, storage driver type, kernel version, and available plugins.
Search Docker Hub for Images
The docker search command searches Docker Hub for publicly available images matching your search term. This helps you discover official images and community-maintained alternatives before pulling them.
docker search ubuntuThis searches Docker Hub for images containing “ubuntu” in their name or description. The results include the image name, description, star count, and whether it’s an official image. Official images are maintained by Docker and the software vendor, providing higher reliability and security.
Run Containers from Images
The docker run command creates and starts a new container from an image. For example, to run a container from the ubuntu image:
docker run -it ubuntu:latest /bin/bashThis starts a new container from the ubuntu image and opens a shell inside the container.
List Running Containers
The docker ps command lists all running containers and provides information about each, including container ID, image name, and status.
docker psThis displays a list of all running containers.
List Downloaded Images
The docker images command lists all available images and supplies information about each image, including image ID, repository, and tag.
docker imagesThis displays a list of all available images.
Build Images from Dockerfiles
The docker build command builds a new image from a Dockerfile, a script containing instructions for building an image.
docker build -t myimage:latest .This builds a new image called myimage using the Dockerfile in the current directory.
Stop Running Containers
The docker stop command stops a running container. For example, to stop a container with the ID abcdefg:
docker stop abcdefgThis stops the container with the ID abcdefg.
Remove Containers
Use the docker rm command to remove a container. For example, to eliminate a container with the ID abcdefg:
docker rm abcdefgThis removes the container with the ID abcdefg.
Remove Images
The docker rmi command removes an image. For example, to eliminate an image with the ID 1234567:
docker rmi 1234567This removes the image with the ID 1234567.
Manage Docker Networks
The docker network command manages Docker networks. It offers options to create, list, and remove networks.
docker network create mynetworkThis creates a new network called mynetwork.
Manage Docker Volumes
The docker volume command manages Docker volumes, providing options to create, list, and remove volumes.
docker volume create myvolumeThis creates a new volume called myvolume.
Save Container Changes as Images
When working with Docker containers, changing the container you want to save as a new image is common. You can use the docker commit command to commit changes in a container to a Docker image.
First, start a new container from the base image and make any necessary changes to the container. For example, to start a new container from the ubuntu image and open a shell inside the container, you can use the following command:
docker run -it --name mycontainer ubuntu:latest /bin/bashThis command will start a new container from the ubuntu image and open a shell inside the container. You can make any necessary changes to the container, such as installing new software or modifying configuration files.
Once you have made the necessary changes, you can use the docker commit command to create a new image from the container. For example, to create a new image called myimage with the changes made in the mycontainer container, you can use the following command:
docker commit mycontainer myimage:latestThis command will create a new image called myimage with the changes made in the mycontainer container. You can now use this new image to create and run new containers with the updated software or configuration.
It’s important to note that the docker commit command only saves changes made to the container’s file system and does not save changes to the container’s networking or storage. If you need to save changes to these areas, use other Docker commands, such as docker network or docker volume.
Security Best Practices
Securing your Docker installation protects both containers and the host system from potential vulnerabilities. Follow these essential security practices when working with Docker on Ubuntu:
Run containers with least privilege: Avoid running containers as root when possible. Use the --user flag to specify a non-root user inside containers, limiting potential damage if a container is compromised.
Keep Docker updated: Regularly update Docker and the host system to receive security patches and bug fixes. Subscribe to Docker security advisories and apply updates promptly.
sudo apt update && sudo apt install --only-upgrade docker-ce docker-ce-cli containerd.ioThis sequence refreshes the package lists and upgrades only the Docker components, leaving the rest of your system untouched.
Consider configuring unattended-upgrades to automatically apply security updates to Docker and the host system, ensuring your environment stays protected against known vulnerabilities.
Enable Docker Content Trust: Docker Content Trust uses digital signatures to verify the publisher and integrity of images. Enable it by setting the environment variable:
export DOCKER_CONTENT_TRUST=1This ensures you only pull signed and verified images from trusted publishers.
Limit network exposure: Only expose necessary ports when running containers. Use specific port mappings instead of exposing all ports, and bind to localhost (127.0.0.1) instead of 0.0.0.0 when services don’t need external access. For remote management, use SSH tunneling to access container services securely.
docker run -p 127.0.0.1:8080:80 nginxThis runs an Nginx container with port 80 only accessible from the local machine on port 8080.
Scan images for vulnerabilities: Use Docker Scout or third-party tools to scan images for known security vulnerabilities before deploying them to production.
Implement resource limits: Prevent containers from consuming excessive system resources by setting memory and CPU limits using the --memory and --cpus flags.
Monitor for intrusion attempts: Use Fail2ban on your host system to detect and block repeated unauthorized access attempts to services running in containers.
Troubleshooting Common Issues
When working with Docker on Ubuntu, you may encounter common issues. This section covers the most frequent problems and their solutions.
Docker Daemon Not Starting
If the Docker daemon fails to start, check the service status first:
sudo systemctl status dockerA failed service typically shows output like:
● docker.service - Docker Application Container Engine
Loaded: loaded (/lib/systemd/system/docker.service; enabled)
Active: failed (Result: exit-code) since Sat 2025-11-30 10:15:00 UTC
Process: 1234 ExecStart=/usr/bin/dockerd (code=exited, status=1/FAILURE)
Review the Docker logs for specific error messages:
sudo journalctl -u docker -n 50 --no-pagerThis displays the last 50 log entries for the Docker service. Common causes include configuration syntax errors in /etc/docker/daemon.json, port conflicts, or insufficient system resources.
To resolve configuration issues, validate your daemon.json file syntax and restart the service:
sudo systemctl restart dockerIf Docker still fails to start, ensure it’s enabled for automatic startup:
sudo systemctl enable dockerPermission Errors When Running Docker Commands
If you see permission errors when running Docker commands without sudo, the error typically looks like:
docker: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/create": dial unix /var/run/docker.sock: connect: permission denied.
This occurs because your user is not in the docker group. Verify your group membership:
groupsIf “docker” doesn’t appear in the output, add your user to the group:
sudo usermod -aG docker $USERActivate the group membership immediately using:
newgrp dockerAlternatively, log out and back in to apply the group changes system-wide.
If you encounter errors related to the Docker daemon socket (/var/run/docker.sock), check the socket permissions:
ls -l /var/run/docker.sockThe socket should be owned by root:docker with permissions srw-rw----. If permissions are incorrect, restart the Docker service to recreate the socket with proper permissions.
Container Networking Issues
If containers cannot reach external networks or other containers, verify Docker’s network configuration:
docker network lsA healthy Docker installation shows three default networks:
NETWORK ID NAME DRIVER SCOPE
a1b2c3d4e5f6 bridge bridge local
g7h8i9j0k1l2 host host local
m3n4o5p6q7r8 none null localIf the bridge network is missing, restart Docker with sudo systemctl restart docker to recreate the default networks. If you use ufw or firewalld, review the firewall warning at the beginning of this guide, as these firewalls may block container traffic by default.
Test container networking by running a simple network test:
docker run --rm busybox ping -c 3 google.comIf this fails, check your host’s DNS configuration and ensure Docker can access /etc/resolv.conf.
Remove Docker from Ubuntu
To completely remove Docker from your Ubuntu system, uninstall the Docker packages:
sudo apt purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extrasRemove the Docker repository and GPG key:
sudo rm /etc/apt/sources.list.d/docker.sources
sudo rm /etc/apt/keyrings/docker.ascThe 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 all Docker data including images, containers, and volumes:
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerdRemove any custom Docker daemon configuration:
sudo rm -rf /etc/dockerDocker Documentation and Resources
Explore these official Docker resources for further learning:
- Docker Documentation: Comprehensive guides for configuring and using Docker.
- Post-installation Steps: Official guide for configuring Docker after installation.
- Docker Security: Best practices for securing Docker deployments.
Conclusion
You now have Docker installed and configured on Ubuntu with the official APT repository providing automatic updates. The setup includes systemd service management for controlling Docker, non-root user access through the docker group, and basic security configurations. From here, explore Docker Compose for multi-container applications, configure log rotation for production use, or set up Docker networks for container communication.
