Docker Installation¶

macOS¶

Install one of the supported Docker providers:

• OrbStack: Recommended, easiest to install, most performant, commercial, not open-source.
• Lima: Free, open-source.
• Docker Desktop: Familiar, popular, not open-source, may require license, may be unstable.
• Rancher Desktop: Free, open-source, simple installation, slower startup.
• Colima: Free, open-source. Depends on separate Lima installation (managed by Homebrew).

OrbStack¶

OrbStack is a newer Docker provider that is very popular with DDEV users because it’s fast, lightweight, and easy to install. It’s a good choice for most users. It is not open-source, and it is not free for professional use.

1. Install OrbStack with brew install orbstack or download it directly.
2. Run the OrbStack app (from Applications) to finish setup, choosing “Docker” as the option. Answer any prompts to allow OrbStack access.

Lima¶

Lima is a free and open-source project supported by the Cloud Native Computing Foundation.

1. Install Lima with brew install lima.
2. If you don’t have the docker client (if docker help fails) then install it with brew install docker.
3. Create a 100GB VM in Lima with 4 CPUs, 6GB memory, and Cloudflare DNS. Adjust to your own needs:

   limactl create --name=default --vm-type=vz --mount-type=virtiofs --mount-writable --memory=6 --cpus=4 --disk=100 template:docker
   docker context create lima-default --docker "host=unix://$HOME/.lima/default/sock/docker.sock"
   docker context use lima-default
   

   After the initial run above, you can use limactl start. Run limactl list to see configured setup.

When your computer restarts, you’ll need to limactl start again.

Docker Desktop for Mac¶

Docker Desktop for Mac can be downloaded from docker.com. It has long been supported by DDEV and has extensive automated testing. It is not open-source, may require a license for many users, and sometimes has stability problems.

Rancher Desktop¶

Rancher Desktop is an easy-to-install free and open-source Docker provider. Install from Rancher Desktop. It has automated testing with DDEV. When installing, choose only the Docker option and turn off Kubernetes.

Colima¶

Colima is a free and open-source project which bundles Lima.

1. Install Colima with brew install colima, which also installs Lima and other dependencies.
2. If you don’t have the docker client (if docker help fails) then install it with brew install docker.

3. Start Colima with 4 CPUs, 6GB memory, 100GB storage, and Cloudflare DNS, adjusting as needed:

   colima start --cpu 4 --memory 6 --disk 100 --vm-type=vz --mount-type=virtiofs --dns=1.1.1.1
   

After the initial run above, you can use colima start or use colima start -e to edit the configuration file. Run colima status at any time to check Colima’s status.

Docker Buildx¶

DDEV requires the Docker buildx plugin. Most Docker providers (OrbStack, Docker Desktop, Rancher Desktop, Colima, Lima) already include it. If docker buildx version doesn’t work, install it with:

brew install docker-buildx

More information in Docker buildx requirement.

Migrating Projects Between Docker Providers¶

• OrbStack has built-in migration of images and volumes from Docker Desktop.
• Move projects between other Docker providers using How can I migrate from one Docker provider to another?.

Linux¶

• Docker: Recommended, free, open-source, best performance and stability.
• Docker rootless: Experimental support, free, open-source, more complex setup, has limitations.
• Podman: Experimental support, free, open-source, more complex setup, has limitations.
• Docker Desktop: Not open-source, may require license, may be unstable, doesn’t have explicit support from DDEV and doesn’t have automated test coverage.

Docker for Linux¶

The best way to install Docker on Linux is to use your native package management tool (apt, dnf, etc.) with the official Docker repository. While many Linux distributions provide Docker packages in their own repositories, these are often outdated and may not include the latest features required for stability in a development environment like DDEV. To ensure you’re using a supported version, install Docker directly from the official Docker repository.

Debian/Ubuntu¶

# Ensure sudo credentials are cached for copy/paste of this block
sudo true

# Remove any old/conflicting Docker packages
sudo apt-get remove -y docker.io docker-doc docker-compose podman-docker containerd runc 2>/dev/null || true

# Install prerequisites
sudo apt-get update && sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

# Add Docker’s GPG key
sudo curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Remove old repository files if present
sudo rm -f /etc/apt/keyrings/docker.gpg /etc/apt/sources.list.d/docker.list

# Add Docker repository in deb822 format
printf "Types: deb\nURIs: https://download.docker.com/linux/%s\nSuites: %s\nComponents: stable\nSigned-By: /etc/apt/keyrings/docker.asc\n" \
  "$(. /etc/os-release && echo "$ID")" \
  "$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")" \
  | sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null

# Install Docker CE
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (create group if it doesn’t exist)
sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}

# Start and enable Docker
sudo systemctl enable --now docker

Run newgrp docker to activate the group change in your current shell, then verify with docker run hello-world. (A full log out and back in also works.)

cat > /tmp/install-docker.sh << 'SCRIPT'
#!/usr/bin/env bash
set -euo pipefail
sudo true
sudo apt-get remove -y docker.io docker-doc docker-compose podman-docker containerd runc 2>/dev/null || true
sudo apt-get update && sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL "https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg" -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo rm -f /etc/apt/keyrings/docker.gpg /etc/apt/sources.list.d/docker.list
printf "Types: deb\nURIs: https://download.docker.com/linux/%s\nSuites: %s\nComponents: stable\nSigned-By: /etc/apt/keyrings/docker.asc\n" \
  "$(. /etc/os-release && echo "$ID")" \
  "$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")" \
  | sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}
sudo systemctl enable --now docker
SCRIPT

See the full Docker Engine installation docs for Ubuntu or Debian for more details.

Other Linux Distributions¶

Follow these distribution-specific instructions to set up Docker Engine from the official Docker repository:

• CentOS
• Fedora
• binaries

After installing Docker, add your user to the docker group and enable the Docker daemon to start at boot:

sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}
sudo systemctl enable --now docker

Run newgrp docker to activate the group change in your current shell. See Post-installation steps for Linux for more details.

On systems without systemd or its equivalent—mostly if you’re installing inside WSL2—you’ll need to manually start Docker with service docker start or the equivalent in your distro. You can add this to your shell profile.

Docker Buildx¶

DDEV requires the Docker buildx plugin. Docker CE installed from the official Docker repository includes it. If docker buildx version doesn’t work, install the docker-buildx-plugin package from the Docker repository (e.g. sudo apt-get install docker-buildx-plugin on Debian/Ubuntu) or follow any of the installation instructions from Docker buildx.

More information in Docker buildx requirement.

Docker Rootless¶

DDEV has experimental support for Docker rootless mode on Linux. See Podman and Docker Rootless in DDEV for details.

Podman for Linux¶

DDEV has experimental support for Podman on Linux. See Podman and Docker Rootless in DDEV for details.

Docker Desktop for Linux¶

Docker Desktop for Linux can be downloaded from docker.com. Casual manual testing seems to work, but DDEV does not have explicit support for it and does not have automated testing.

Windows¶

For DDEV on Windows, choose one of these Docker providers:

• Docker CE inside WSL2 - The most popular, performant, and best-supported way to run DDEV on Windows. The DDEV installer installs Docker CE automatically. Requires WSL2.
• Docker Desktop for Windows - Works with both WSL2 and traditional Windows. Extensive automated testing with DDEV, but has some performance and reliability problems. Not open-source; may require a license for many users.
• Rancher Desktop for Windows - Free and open-source. Manually tested with DDEV on traditional Windows; no automated testing. Works with both WSL2 and traditional Windows.

Install WSL2¶

In PowerShell, run:

# Install WSL2; reboot if prompted, then continue:
wsl --install --no-distribution

# Update WSL2 if previously installed:
wsl --update

Create an Ubuntu distro (skip if you’re using Traditional Windows):

# You'll be asked to set a username and password for the distro:
wsl --install Ubuntu-24.04 --name DDEV

Verify the “DDEV” distro is set as default:

> wsl -l -v
  NAME                   STATE           VERSION
* DDEV                   Stopped         2

Docker CE inside WSL2¶

The DDEV Windows installer automatically installs Docker CE in your WSL2 environment — no manual Docker installation is needed. After installing WSL2 above, proceed to install DDEV.

To install Docker CE manually instead, open your WSL2 terminal (Ubuntu) and run:

# Ensure sudo credentials are cached for copy/paste of this block
sudo true

# Remove any old/conflicting Docker packages
sudo apt-get remove -y docker.io docker-doc docker-compose podman-docker containerd runc 2>/dev/null || true

# Install prerequisites
sudo apt-get update && sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

# Add Docker's 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.asc

# Remove old repository files if present
sudo rm -f /etc/apt/keyrings/docker.gpg /etc/apt/sources.list.d/docker.list

# Add Docker repository in deb822 format
printf "Types: deb\nURIs: https://download.docker.com/linux/ubuntu\nSuites: %s\nComponents: stable\nSigned-By: /etc/apt/keyrings/docker.asc\n" \
  "$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")" \
  | sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null

# Install Docker CE
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (create group if it doesn't exist)
sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}

Run newgrp docker to activate the group change in your current shell. On WSL2 systems without systemd, you may need to start Docker manually with sudo service docker start.

cat > /tmp/install-docker.sh << 'SCRIPT'
#!/usr/bin/env bash
set -euo pipefail
sudo true
sudo apt-get remove -y docker.io docker-doc docker-compose podman-docker containerd runc 2>/dev/null || true
sudo apt-get update && sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo rm -f /etc/apt/keyrings/docker.gpg /etc/apt/sources.list.d/docker.list
printf "Types: deb\nURIs: https://download.docker.com/linux/ubuntu\nSuites: %s\nComponents: stable\nSigned-By: /etc/apt/keyrings/docker.asc\n" \
  "$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")" \
  | sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}
SCRIPT

Docker Desktop for Windows¶

1. Download and install Docker Desktop from docker.com.
2. During installation, ensure “Use WSL 2 instead of Hyper-V” is selected.
3. After installation, open Docker Desktop settings and navigate to Resources → WSL Integration.
4. Enable integration with your Ubuntu-based WSL2 distro (e.g., Ubuntu, Ubuntu-24.04, Ubuntu-22.04).
5. Apply the changes and restart Docker Desktop if prompted.
6. Verify that docker ps works in git-bash, PowerShell, or WSL2, wherever you’re using it.

Rancher Desktop for Windows¶

1. Download and install Rancher Desktop.
2. During installation, choose Docker as the container runtime and disable Kubernetes.
3. After installation, open Rancher Desktop and go to WSL Integration in the settings.
4. Enable integration with your Ubuntu-based WSL2 distro (e.g., Ubuntu, Ubuntu-24.04, Ubuntu-22.04).
5. Apply the changes and restart Rancher Desktop if needed.
6. Verify that docker ps works in git-bash, PowerShell, or WSL2, wherever you’re using it.

Docker Buildx¶

DDEV requires the Docker buildx plugin. Docker CE inside WSL2, Docker Desktop, and Rancher Desktop all include it. If docker buildx version doesn’t work, install the docker-buildx-plugin package inside WSL2 (e.g. sudo apt-get install docker-buildx-plugin on Ubuntu).

More information in Docker buildx requirement.

GitHub Codespaces¶

You can set up GitHub Codespaces following the instructions in the DDEV Installation section.