DDEV Installation¶

macOS¶

Homebrew¶

Homebrew is the easiest and most reliable way to install and upgrade DDEV:

# Install DDEV
brew install ddev/ddev/ddev

# One-time initialization of mkcert
mkcert -install

For unusual browsers and situations that don’t automatically support the mkcert certificate authority, configure your browser.

Install Script¶

The install script is another option. It downloads, verifies, and sets up the ddev executable:

# Download and run the install script
curl -fsSL https://ddev.com/install.sh | bash

For unusual browsers and situations that don’t automatically support the mkcert certificate authority, configure your browser.

# Download and run the script to install DDEV v1.24.10
curl -fsSL https://ddev.com/install.sh | bash -s v1.24.10

Linux¶

Debian/Ubuntu¶

DDEV’s Debian and RPM packages work with apt and yum repositories and most variants that use them, including Windows WSL2:

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

# Add DDEV’s GPG key to your keyring
sudo apt-get update && sudo apt-get install -y curl
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://pkg.ddev.com/apt/gpg.key | sudo tee /etc/apt/keyrings/ddev.asc > /dev/null
sudo chmod a+r /etc/apt/keyrings/ddev.asc

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

# Add DDEV releases to your package repository
printf "Types: deb\nURIs: https://pkg.ddev.com/apt/\nSuites: *\nComponents: *\nSigned-By: /etc/apt/keyrings/ddev.asc\n" | sudo tee /etc/apt/sources.list.d/ddev.sources >/dev/null

# Update package information and install DDEV
sudo apt-get update && sudo apt-get install -y ddev

# One-time initialization of mkcert
mkcert -install

cat > /tmp/install-ddev.sh << 'SCRIPT'
#!/usr/bin/env bash
set -euo pipefail
sudo true
sudo apt-get update && sudo apt-get install -y curl
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://pkg.ddev.com/apt/gpg.key | sudo tee /etc/apt/keyrings/ddev.asc > /dev/null
sudo chmod a+r /etc/apt/keyrings/ddev.asc
sudo rm -f /etc/apt/keyrings/ddev.gpg /etc/apt/sources.list.d/ddev.list
printf "Types: deb\nURIs: https://pkg.ddev.com/apt/\nSuites: *\nComponents: *\nSigned-By: /etc/apt/keyrings/ddev.asc\n" | sudo tee /etc/apt/sources.list.d/ddev.sources >/dev/null
sudo apt-get update && sudo apt-get install -y ddev
mkcert -install
SCRIPT

For unusual browsers and situations that don’t automatically support the mkcert certificate authority, configure your browser.

sudo rm -f /usr/local/bin/ddev /usr/local/bin/mkcert

Fedora, Red Hat, etc.¶

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

# Add DDEV releases to your package repository
echo '[ddev]
name=ddev
baseurl=https://pkg.ddev.com/yum/
gpgcheck=0
enabled=1' | sed 's/^ \+//' | sudo tee /etc/yum.repos.d/ddev.repo >/dev/null

# Install DDEV
sudo dnf install --refresh ddev

# One-time initialization of mkcert
mkcert -install

cat > /tmp/install-ddev.sh << 'SCRIPT'
#!/usr/bin/env bash
set -euo pipefail
sudo true
printf "[ddev]\nname=ddev\nbaseurl=https://pkg.ddev.com/yum/\ngpgcheck=0\nenabled=1\n" | sudo tee /etc/yum.repos.d/ddev.repo >/dev/null
sudo dnf install --refresh ddev
mkcert -install
SCRIPT

For unusual browsers and situations that don’t automatically support the mkcert certificate authority, configure your browser.

Signed yum repository support will be added in the future.

Arch Linux¶

We maintain the ddev-bin package in AUR for Arch-based systems including Arch Linux, EndeavourOS and Manjaro. Install with yay or your AUR tool of choice.

# Install DDEV
yay -S ddev-bin

# One-time initialization of mkcert
mkcert -install

For unusual browsers and situations that don’t automatically support the mkcert certificate authority, configure your browser.

Homebrew¶

# Install DDEV using Homebrew
brew install ddev/ddev/ddev

# One-time initialization of mkcert
mkcert -install

For unusual browsers and situations that don’t automatically support the mkcert certificate authority, configure your browser.

Install Script¶

The install script is another option. It downloads, verifies, and sets up the ddev executable:

# Download and run the install script
curl -fsSL https://ddev.com/install.sh | bash

For unusual browsers and situations that don’t automatically support the mkcert certificate authority, configure your browser.

# Download and run the script to install DDEV v1.24.10
curl -fsSL https://ddev.com/install.sh | bash -s v1.24.10

Windows¶

DDEV on Windows uses an installer that supports three configurations — pick the one that fits you:

Step 1: 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

Step 2: Install DDEV¶

Download the installer — make sure to pick the right architecture:

• AMD64 (x86-64): Most traditional Windows PCs (Intel/AMD processors)
• ARM64: Windows on ARM devices like Microsoft Surface Pro X, Surface Pro 9 (5G), or other ARM-based Windows devices

Run the installer and select your mode. For WSL2 modes, the installer will ask which distro to use — enter the name you chose in Step 1. The installer will automatically configure DDEV for your chosen Docker provider. If you run the wrong installer for your architecture, it will detect the mismatch and direct you to download the correct one.

winget install --interactive DDEV

# WSL2 with Docker CE and specified distro, silently
winget install DDEV --silent --override '/docker-ce /distro=DDEV'

winget uninstall DDEV --all-versions

choco install ddev

# WSL2 with Docker CE and specified distro
./ddev_windows_amd64_installer.exe /S /docker-ce /distro=DDEV

# WSL2 with Docker Desktop and specified distro
./ddev_windows_amd64_installer.exe /S /docker-desktop /distro=Ubuntu

# Traditional Windows (requires Docker Desktop/Rancher Desktop)
./ddev_windows_installer.exe /S /traditional

# Get help with all options
./ddev_windows_amd64_installer.exe /help

Step 3: Start working in WSL2¶

(Skip if using Traditional Windows.)

Open your distro from the Start menu (or run wsl in PowerShell) to get a Linux terminal. Run all ddev commands here — never in PowerShell or Git Bash.

Store your projects inside WSL2 (e.g. /home/<username>/projects), not on C:\ drive (/mnt/c in WSL2) — faster and avoids permission issues.

From Windows Explorer: Linux → DDEV → home → [username].

GitHub Codespaces¶

You can use DDEV in remote GitHub Codespaces without having to run Docker locally; you only need a browser and an internet connection.

Start by creating a .devcontainer/devcontainer.json file in your GitHub repository:

{
    "image": "mcr.microsoft.com/devcontainers/base:debian-12",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {
            "version": "latest"
        },
        "ghcr.io/ddev/ddev/install-ddev:latest": {}
    }
}

The install-ddev feature automatically configures the environment and sets up DDEV for use in Codespaces.

Launch your repository in Codespaces:

DDEV is now available within your new codespace instance:

Run ddev config to start a new blank project - or install a CMS.

Run ddev start if there is already a configured DDEV project in your repository.

Troubleshooting:

If there are errors after restarting a codespace, use ddev restart or ddev poweroff.

You can also use the commands

• “Codespaces: Rebuild container”
• “Codespaces: Full rebuild container” (Beware: database will be deleted)

via the Visual Studio Code Command Palette:

• ⌘ + SHIFT + P on a Mac
• CTRL + SHIFT + P on Windows/Linux
• from the Application Menu, click View > Command Palette (Firefox)

If you need DDEV-specific assistance or have further questions, see support.

Your updated devcontainer.json file may differ depending on your project, but you should have install-ddev in the features section.

Docker integration¶

DDEV in Codespaces relies on docker-in-docker, which must be added manually to the features when using "mcr.microsoft.com/devcontainers/base:debian-12". See devcontainers/features for general support and issues regarding Docker-support.

DDEV’s router is not used¶

Since Codespaces handles all the routing, the internal DDEV router will not be used on Codespaces. Therefore config settings like web_extra_exposed_ports will have no effect.

You can expose ports via the ports setting, which is usually not recommended if you work locally due to port conflicts. But you can load these additional Docker compose files only when Codespaces is detected. See Defining Additional Services for more information.

services:
    web:
        ports:
            - "5174:5174"

Default environment variables¶

Codespace instances already provide some default environment values. You can inherit and inject them in your .ddev/config.yaml:

web_environment:
    - CODESPACES
    - CODESPACE_NAME
    - GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN

Advanced usage via devcontainer.json¶

A lot more customization is possible via the devcontainer.json-configuration. You can install Visual Studio Code extensions by default or run commands automatically.

postCreateCommand¶

The postCreateCommand lets you run commands automatically when a new codespace is launched. DDEV commands are available here.

The event is triggered on: fresh creation, rebuilds and full rebuilds. ddev poweroff is used in this example to avoid errors on rebuilds since some Docker containers are kept.

You usually want to use a separate bash script to do this, as docker might not yet be available when the command starts to run.

{
    "image": "mcr.microsoft.com/devcontainers/base:debian-12",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {
            "version": "latest"
        },
        "ghcr.io/ddev/ddev/install-ddev:latest": {}
    },
    "portsAttributes": {
        "3306": {
            "label": "database"
        },
        "8027": {
            "label": "mailpit"
        },
        "8080": {
            "label": "web http"
        },
        "8443": {
            "label": "web https"
        }
    },
    "postCreateCommand": "bash .devcontainer/setup_project.sh"
}

The install-ddev feature provides its own postCreateCommand to verify DDEV installation. User-provided commands run after the feature’s commands.

#!/usr/bin/env bash
set -ex

wait_for_docker() {
  while true; do
    docker ps > /dev/null 2>&1 && break
    sleep 1
  done
  echo "Docker is ready."
}

wait_for_docker

# download images beforehand, optional
ddev utility download-images

# avoid errors on rebuilds
ddev poweroff

# start ddev project automatically
ddev start -y

# further automated install / setup steps, e.g.
ddev composer install

To check for errors during the postCreateCommand action, use the command

• “Codespaces: View creation log”

via the Visual Studio Code Command Palette:

• ⌘ + SHIFT + P on a Mac
• CTRL + SHIFT + P on Windows/Linux
• from the Application Menu, click View > Command Palette (Firefox)

Manual¶

DDEV is a single executable, so installation on any OS is a matter of copying the ddev executable for your architecture into the appropriate system path on your machine.

• Download and extract the latest DDEV release for your architecture.
• Move ddev to /usr/local/bin with mv ddev /usr/local/bin/ (may require sudo), or another directory in your $PATH as preferred.
• Run ddev to test your installation. You should see DDEV’s command usage output.

• As a one-time initialization, run mkcert -install, which may require your sudo password.

  If you don’t have mkcert installed, download the latest release for your architecture and sudo mv <downloaded_file> /usr/local/bin/mkcert && sudo chmod +x /usr/local/bin/mkcert.

• For unusual browsers and situations that don’t automatically support the mkcert certificate authority, configure your browser.