Docker Installation¶

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.

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?.

Podman on macOS runs containers in a lightweight VM managed by podman machine. You can also use Podman Desktop for a GUI.

ddev config global --router-http-port=8080 --router-https-port=8443

Install Podman¶

Install Podman using Homebrew:

brew install podman

Or install Podman Desktop if you prefer a GUI. For more information, see the official Podman installation guide for macOS and the Podman tutorials.

Install the Docker CLI¶

Podman provides a Docker-compatible API, so you can use the Docker CLI as a front-end for Podman. This lets you use familiar docker commands, switch between runtimes with Docker contexts, and keep compatibility with tools that expect the docker command.

brew install docker

Initialize and start the Podman machine¶

# check `podman machine init -h` for more options
podman machine init --provider applehv
podman machine start

Point the Docker CLI at Podman¶

SOCKET=$(podman machine inspect | jq -r '.[0].ConnectionInfo.PodmanSocket.Path')
docker context create podman-rootless \
    --description "Podman (rootless)" \
    --docker "host=unix://${SOCKET}"
docker context use podman-rootless
docker ps

Reclaim disk space¶

podman machine start
podman machine ssh 'sudo fstrim -av'

Install one of the supported Docker providers:

• Docker CE: Recommended, free, open-source, best performance and stability. Install from the official Docker repository.
• Docker Desktop for Linux: Not explicitly supported by DDEV and has no automated testing.

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 sg docker to open a new subshell with the docker group active, then verify with docker run hello-world. (A full log out and back in applies the change to your whole session.)

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 sg docker to open a new subshell with the docker group active, or log out and back in to apply the change to your whole session. 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 Desktop for Linux¶

As an alternative to Docker CE, 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.

Docker rootless mode runs the Docker daemon and containers as a non-root user, which reduces the attack surface (no root daemon, container processes can’t touch root-owned files). DDEV supports Docker rootless on Linux and WSL2, with full Docker compatibility.

Install Docker rootless¶

Follow the official Docker rootless installation guide.

Configure the system¶

# Allow privileged port access if needed
if [ -f /proc/sys/net/ipv4/ip_unprivileged_port_start ]; then
  if [ "1024" = "$(cat /proc/sys/net/ipv4/ip_unprivileged_port_start)" ]; then
    echo 'net.ipv4.ip_unprivileged_port_start=0' | sudo tee -a /etc/sysctl.d/60-rootless.conf
    sudo sysctl --system
  fi
fi
# Allow loopback connections (needed for working Xdebug)
# See https://github.com/moby/moby/issues/47684#issuecomment-2166149845
mkdir -p ~/.config/systemd/user/docker.service.d
cat << 'EOF' > ~/.config/systemd/user/docker.service.d/override.conf
[Service]
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_DISABLE_HOST_LOOPBACK=false"
EOF

Enable the Docker socket¶

systemctl --user enable --now docker.socket

# You should see `/run/user/1000/docker.sock` (the number may vary):
ls $XDG_RUNTIME_DIR/docker.sock

Point the Docker CLI at the rootless socket¶

# View existing contexts
docker context ls

# Create the rootless context if it doesn't exist
docker context inspect rootless >/dev/null 2>&1 || \
    docker context create rootless \
        --description "Rootless runtime socket" \
        --docker host="unix://$XDG_RUNTIME_DIR/docker.sock"

# Switch to the context
docker context use rootless

# Verify it works
docker ps

Podman is rootless by default, which makes it a good fit for environments that forbid Docker or require rootless operation. Podman is slower than Docker and has more setup, but Podman rootless on Linux is solid.

Install Podman¶

Install Podman with your distribution’s package manager (see the official Podman installation guide for Linux):

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install podman
# Fedora
sudo dnf install --refresh podman

# Ubuntu/Debian
sudo apt-get install -y uidmap && sudo apt-mark manual uidmap
sudo apt-get purge -y --auto-remove podman crun netavark aardvark-dns
# Fedora
sudo dnf remove -y podman crun netavark aardvark-dns

brew install podman
hash -r

You can also install Podman Desktop if you prefer a GUI. For more information, see the Podman tutorials.

Install the Docker CLI and buildx¶

Podman provides a Docker-compatible API, so you can use the Docker CLI as a front-end for Podman. This lets you use familiar docker commands, switch between runtimes with Docker contexts, and keep compatibility with tools that expect the docker command.

1. Set up Docker’s repository.

2. Install the CLI and the buildx plugin (you don’t need docker-ce, the Docker engine):

   # Ubuntu/Debian
   sudo apt-get update && sudo apt-get install docker-ce-cli docker-buildx-plugin
   # Fedora
   sudo dnf install --refresh docker-ce-cli docker-buildx-plugin
   

Configure Podman rootless¶

Prepare the system by configuring subuid/subgid ranges and enabling userns options (see the Arch Linux Wiki for details). If another user on this machine already holds 100000-165535, give yourself a range that doesn’t overlap theirs — two users mapping the same host IDs break each other’s containers:

# Add subuid and subgid ranges if they don't exist for the current user
grep "^$(id -un):\|^$(id -u):" /etc/subuid >/dev/null 2>&1 || sudo usermod --add-subuids 100000-165535 $(whoami)
grep "^$(id -un):\|^$(id -u):" /etc/subgid >/dev/null 2>&1 || sudo usermod --add-subgids 100000-165535 $(whoami)
# Propagate changes to subuid and subgid
podman system migrate
# Debian requires setting unprivileged_userns_clone
if [ -f /proc/sys/kernel/unprivileged_userns_clone ]; then
  if [ "1" != "$(cat /proc/sys/kernel/unprivileged_userns_clone)" ]; then
    echo 'kernel.unprivileged_userns_clone=1' | sudo tee -a /etc/sysctl.d/60-rootless.conf
    sudo sysctl --system
  fi
fi
# Fedora requires setting max_user_namespaces
if [ -f /proc/sys/user/max_user_namespaces ]; then
  if [ "0" = "$(cat /proc/sys/user/max_user_namespaces)" ]; then
    echo 'user.max_user_namespaces=28633' | sudo tee -a /etc/sysctl.d/60-rootless.conf
    sudo sysctl --system
  fi
fi
# Allow privileged port access if needed
if [ -f /proc/sys/net/ipv4/ip_unprivileged_port_start ]; then
  if [ "1024" = "$(cat /proc/sys/net/ipv4/ip_unprivileged_port_start)" ]; then
    echo 'net.ipv4.ip_unprivileged_port_start=0' | sudo tee -a /etc/sysctl.d/60-rootless.conf
    sudo sysctl --system
  fi
fi

Enable the Podman socket and verify it’s running (see the Podman socket activation documentation):

systemctl --user enable --now podman.socket

# You should see `/run/user/1000/podman/podman.sock` (the number may vary):
ls $XDG_RUNTIME_DIR/podman/podman.sock

# You can also check the socket path with:
podman info --format '{{.Host.RemoteSocket.Path}}'

Configure the Docker CLI to use Podman (see the Podman rootless tutorial):

# View existing contexts
docker context ls

# Create Podman rootless context
docker context create podman-rootless \
    --description "Podman (rootless)" \
    --docker host="unix://$XDG_RUNTIME_DIR/podman/podman.sock"

# Switch to the new context
docker context use podman-rootless

# Verify it works
docker ps

sudo mount --make-rshared /

[boot]
command = mount --make-rshared /

Validate the setup¶

DDEV ships a script that checks everything on this page and explains anything it finds. It works with any Podman install, however you got it, and changes nothing unless you ask it to install:

curl -fsSL https://raw.githubusercontent.com/ddev/ddev/main/scripts/linux-podman-rootless.sh -o /tmp/podman-rootless.sh
bash /tmp/podman-rootless.sh

It verifies the Podman and netavark version pairing, the socket, cgroup manager, subuid/subgid ranges, privileged ports, the Docker context, and buildx. It then stops inferring and starts testing: it runs a real container, builds an image and loads it back into the engine, and watches a container healthcheck report healthy. Those last three are the steps ddev start fails at on a machine where everything else looks correct. To perform the whole setup described above instead of just checking it, run the script with --install. There’s also --install-brew for the Homebrew last resort, which is what DDEV’s CI uses.

Podman rootless performance optimization¶

What’s slower under Podman rootless is container image and filesystem work: ddev start, image builds, ddev import-db, ddev export-db, ddev snapshot (see Podman run/build performance issues and the Podman performance documentation). Serving your site is not — once the containers are up, requests go through the same web server, PHP, and database as under Docker. The storage driver is the biggest lever on the operations that are affected.

On Linux kernel 5.13 and newer, Podman uses native rootless overlay, which is the fastest option and needs no configuration at all. Check what you’re getting:

podman info --format '{{.Store.GraphDriverName}} {{index .Store.GraphStatus "Native Overlay Diff"}}'

overlay true means you’re already on the fast path — do nothing. If it prints overlay false, something has configured the fuse-overlayfs mount program, which disables native overlay diff; remove mount_program from ~/.config/containers/storage.conf to get the faster native path back.

Podman rootless troubleshooting¶

The Docker CLI hides most Podman-side errors behind a generic message. When something fails, read the real error from the Podman service:

journalctl --user -u podman.service --since '-5min'

Install one of the supported Docker providers:

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

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 sg docker to open a new subshell with the docker group active, or log out and back in to apply the change to your whole session. 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 Debian-based WSL2 distro (e.g., Ubuntu-26.04, Debian).
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 Debian-based WSL2 distro (e.g., Ubuntu-26.04, Debian).
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 rootless runs inside WSL2 using the same setup as Linux. In your WSL2 distro, follow the Docker rootless instructions for Linux.

Windows users can run Podman via Podman Desktop, which manages the WSL2-based VM for you. Podman on Windows works but is less mature than on Linux.

Install Podman¶

Install Podman Desktop, which includes Podman. Alternatively, install Podman directly following the official Podman installation guide for Windows. For more information, see the Podman tutorials.

Configure Podman¶

Setup and configuration follow the same patterns as the Linux/WSL2 setup, but with Podman Desktop managing the VM for you. Follow the Podman rootless instructions for Linux.