DDEV Installation

Once you’ve installed a Docker provider, you’re ready to install DDEV!

=== "macOS"

## macOS

### Homebrew

[Homebrew](https://brew.sh/) is the easiest and most reliable way to install and [upgrade](./ddev-upgrade.md) DDEV:

```bash
# 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](configuring-browsers.md).

### Install Script

The [install script](https://github.com/ddev/ddev/blob/main/scripts/install_ddev.sh) is another option. It downloads, verifies, and sets up the `ddev` executable:

```bash
# 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](configuring-browsers.md).

??? "Do you still have an old version after installing or upgrading?"
    If `ddev --version` still shows an older version than you installed or upgraded to, use `which -a ddev` to find out where another version of the `ddev` executable must be installed. See the ["Why Do I Have An Old DDEV" FAQ](../usage/faq.md#why-do-i-have-an-old-ddev).
??? "Need a specific version?"
    Use the `-s` argument to specify a specific stable or prerelease version:

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

=== "Linux"

## Linux

### Debian/Ubuntu

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

```bash
# 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
```

??? tip "Prefer to run as a script?"
    Create a script file, then run it:

    ```bash
    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
    ```

    Review the script, then run it: `bash /tmp/install-ddev.sh`

For unusual browsers and situations that don't automatically support the `mkcert` certificate authority, [configure your browser](configuring-browsers.md).

??? "Do you still have an old version after installing or upgrading?"
    If `ddev --version` still shows an older version than you installed or upgraded to, use `which -a ddev` to find out where another version of the `ddev` executable must be installed. See the ["Why Do I Have An Old DDEV" FAQ](../usage/faq.md#why-do-i-have-an-old-ddev).

??? "Need to remove a previously-installed variant?"
    If you previously used DDEV’s [install script](#install-script), you can remove that version:

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

    If you previously [installed DDEV with Homebrew](#homebrew), you can run `brew unlink ddev` to get rid of the Homebrew version.

### Fedora, Red Hat, etc.

```bash
# 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
```

??? tip "Prefer to run as a script?"
    Create a script file, then run it:

    ```bash
    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
    ```

    Review the script, then run it: `bash /tmp/install-ddev.sh`

For unusual browsers and situations that don't automatically support the `mkcert` certificate authority, [configure your browser](configuring-browsers.md).

Signed yum repository support will be added in the future.

### Arch Linux

We maintain the [ddev-bin](https://aur.archlinux.org/packages/ddev-bin/) package in AUR for Arch-based systems including Arch Linux, EndeavourOS and Manjaro. Install with `yay` or your AUR tool of choice.

```bash
# 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](configuring-browsers.md).

### Homebrew

```bash
# 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](configuring-browsers.md).

<!-- we’re using HTML here to customize the #install-script-linux anchor -->
<h3 id="install-script-linux">Install Script<a class="headerlink" href="#install-script-linux" title="Permanent link">¶</a></h3>

The [install script](https://github.com/ddev/ddev/blob/main/scripts/install_ddev.sh) is another option. It downloads, verifies, and sets up the `ddev` executable:

```bash
# 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](configuring-browsers.md).

??? "Need a specific version?"
    Use the `-s` argument to specify a specific stable or prerelease version:

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

??? "Do you still have an old version after installing or upgrading?"
    If `ddev --version` still shows an older version than you installed or upgraded to, use `which -a ddev` to find out where another version of the `ddev` executable must be installed. See the ["Why Do I Have An Old DDEV" FAQ](../usage/faq.md#why-do-i-have-an-old-ddev).

=== "Windows"

## Windows

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

| Mode | Best for | Requires |
|---|---|---|
| **Docker CE inside WSL2** (recommended) | Most users, best performance | WSL2 |
| **Docker Desktop / Rancher Desktop with WSL2** | Already have Docker Desktop or Rancher Desktop installed | WSL2 + Docker Desktop or Rancher Desktop |
| **Traditional Windows** | PowerShell/Git Bash workflow | Docker Desktop or Rancher Desktop (no separate WSL2 distro needed) |

### Step 1: Install WSL2

In PowerShell, run:

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

# Update WSL2 if previously installed:
wsl --update
```

Create an Ubuntu or other Debian-based WSL2 distro (skip if you're using Traditional Windows). Ubuntu is recommended:

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

!!!tip "\"DDEV\" is just a suggested name — use any name you like."

!!!tip "Other Debian-based distros also work"
    The DDEV installer supports Ubuntu and Debian and has been tested with Kali Linux and eLxr. If you prefer one of those, substitute its name, for example `wsl --install Debian --name DDEV`.

Verify the "DDEV" distro is set as default:

```powershell { .no-copy }
> wsl -l -v
  NAME                   STATE           VERSION
* DDEV                   Stopped         2
```

### Step 2: Install DDEV

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

<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 1rem; text-align: center;">
[Download for AMD64 :material-microsoft-windows:<br>(Intel/AMD) :material-download:](https://ddev.com/download/ddev_windows_amd64_installer.exe "For computers with Intel or AMD processors (most common)"){ .md-button .md-button--primary }
[Download for ARM64 :material-microsoft-windows:<br>(Snapdragon) :material-download:](https://ddev.com/download/ddev_windows_arm64_installer.exe "For computers with ARM processors like Qualcomm Snapdragon"){ .md-button .md-button--primary }
</div>

- **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

!!!tip "Check your system architecture"
    Not sure which architecture you have? Open PowerShell and run: `$env:PROCESSOR_ARCHITECTURE`. It will show `AMD64` or `ARM64`. Alternatively, in WSL2/Ubuntu run `uname -m` which shows `x86_64` for AMD64 or `aarch64` for ARM64.

Run the installer and select your mode. For WSL2 modes, the installer will display all detected Debian-based WSL2 distros (Ubuntu, Debian, Kali, eLxr, etc.) and prompt you to select one. 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.

??? tip "Install using WinGet"
    [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/) can download and launch the installer interactively:

    ```powershell
    winget install --interactive DDEV
    ```

    For silent/automated installation with specific options, use `--override` to pass installer flags:

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

    If WinGet picks up an old version (which can happen when DDEV was previously installed with the Windows installer), uninstall all versions first:

    ```powershell
    winget uninstall DDEV --all-versions
    ```

??? tip "Install using Chocolatey (Traditional Windows AMD64 only)"
    [Chocolatey](https://chocolatey.org/) has had DDEV support for years and remains an option for Traditional Windows on AMD64:

    ```powershell
    choco install ddev
    ```

??? tip "Installer in Silent Mode"
    The Windows installer supports silent mode for automated installations and testing:

    ```bash
    # 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
    ```

    The `/S` flag makes the installation completely silent. Use `/distro=<name>` to specify your WSL2 distribution name (required for WSL2 options).

??? "Manual Installation"

    ### Windows Manual Installation

    If you prefer to install DDEV manually on WSL2, these techniques can be used to install on a non-Ubuntu distro, and can be adapted for Yum-based or ArchLinux-based distros as well:

    1. In PowerShell, run `mkcert.exe -install` and follow the prompt to install the Certificate Authority.
    2. In PowerShell, run `$env:CAROOT="$(mkcert -CAROOT)"; setx CAROOT $env:CAROOT; If ($Env:WSLENV -notlike "*CAROOT/up:*") { $env:WSLENV="CAROOT/up:$env:WSLENV"; setx WSLENV $Env:WSLENV }`. This will set WSL2 to use the Certificate Authority installed on the Windows side, so your Windows-side browser can trust it.
    3. In PowerShell, run `wsl --update` to make sure you have a current WSL version.
    4. In PowerShell, run `wsl --install <distro-type> --name DDEV`, for example `wsl --install Debian --name DDEV`. This will install the WSL2 distro for you. (The name "DDEV" is just a suggestion; you can use any name you like.)
    5. **Docker CE:** Follow the instructions in the [Linux install section here](docker-installation.md#linux) to install Docker CE and DDEV. In addition, `sudo apt-get install -y docker-ce ddev ddev-wsl2` (or the equivalent `dnf` or other package manager commands).
    6. **Docker Desktop for Windows (if used, this is not preferred):**
        * Download and install the installer from [docker.com](https://www.docker.com/products/docker-desktop/). Choose the WSL2-based configuration. Start Docker Desktop. It may prompt you to log out and log in again, or reboot.
        * Go to Docker Desktop’s *Settings* → *Resources* → *WSL integration* → *enable integration for your distro*. Now `docker` commands will be available from within your WSL2 distro.
    7. Double-check your distro: `echo $CAROOT` should show something like `/mnt/c/Users/<you>/AppData/Local/mkcert`
    8. Check that Docker is working inside Ubuntu (or your distro) by running `docker ps` in the distro.
    9. Open the WSL2 terminal, for example `Debian` from the Windows start menu.
    10. In WSL2, run `mkcert -install`.
    11. Note that the older manual [PowerShell script](https://github.com/ddev/ddev/blob/main/scripts/install_ddev_wsl2_docker_inside.ps1) may be instructional if you’re setting up a non-Ubuntu distro. It has been replaced by the Windows installer, but could be adapted for other distros. Pass `-Distro <name>` when running it.

    !!!note "Path to certificates"
        If you get the prompt `Installing to the system store is not yet supported on this Linux`, you may need to add `/usr/sbin` to the `$PATH` so that `/usr/sbin/update-ca-certificates` can be found.

### 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](../project.md) 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\]**.

!!!note "Custom hostnames"
    Custom hostnames with a non-default [TLD](../configuration/config.md#project_tld) (non `ddev.site`) are managed via the Windows hosts file at `C:\Windows\System32\drivers\etc\hosts`, not within WSL2.

??? "What if my browser (especially Firefox) doesn’t trust `https` URLs?"
    DDEV uses [mkcert](https://github.com/FiloSottile/mkcert) to generate a local certificate authority (CA), and `mkcert -install` registers it with most browsers automatically. Firefox and some other browsers manage their own certificate stores and require a manual import.

    To diagnose certificate trust issues, run `ddev utility tls-diagnose`.

    To manually import the CA: run `mkcert.exe -CAROOT` to find the directory containing `rootCA.pem`, then import that file via your browser’s certificate manager (usually under Security settings → View Certificates → Authorities → Import).

    See [Configuring Browsers](configuring-browsers.md) for full details.

=== "Codespaces"

## GitHub Codespaces

You can use DDEV in remote [GitHub Codespaces](https://github.com/features/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:

```json
{
    "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:

<div style="text-align:center;"><img style="max-width:400px;" src="./../../../images/codespaces-launch.png" alt="Screenshot of codespace create dialog in a repository on GitHub"></div>

<div style="text-align:center;"><img style="max-width:400px;" src="./../../../images/codespaces-setting-up.png" alt="Screenshot of codespace create dialog in a repository on GitHub"></div>

DDEV is now available within your new codespace instance:

<div style="text-align:center;"><img src="./../../../images/codespaces-hello-screen.png" alt=""></div>

Run `ddev config` to [start a new blank project](./../project.md) - or [install a CMS](./../quickstart.md).

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](https://docs.github.com/en/enterprise-cloud@latest/codespaces/codespaces-reference/using-the-vs-code-command-palette-in-codespaces):

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

If you need DDEV-specific assistance or have further questions, see [support](./../support.md).

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

!!!note "Normal Linux installation also works"
    You can also install DDEV as if it were on any normal [Linux installation](#linux).

### Docker integration

DDEV in Codespaces relies on [`docker-in-docker`](https://github.com/devcontainers/features), which must be added manually to the features when using `"mcr.microsoft.com/devcontainers/base:debian-12"`. See [`devcontainers/features`](https://github.com/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`](./../configuration/config.md#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](./../extend/custom-compose-files.md#docker-composeyaml-examples) for more information.

```yaml
services:
    web:
        ports:
            - "5174:5174"
```

### Default environment variables

Codespace instances already provide some [default environment values](https://docs.github.com/en/codespaces/developing-in-codespaces/default-environment-variables-for-your-codespace). You can inherit and inject them in your `.ddev/config.yaml`:

```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](https://containers.dev/implementors/json_reference/). You can install Visual Studio Code extensions by default or run commands automatically.

#### postCreateCommand

The [`postCreateCommand`](https://containers.dev/implementors/json_reference/) 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](https://github.com/devcontainers/features/issues/780).

```json
{
    "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.

```bash
#!/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](https://docs.github.com/en/enterprise-cloud@latest/codespaces/codespaces-reference/using-the-vs-code-command-palette-in-codespaces):

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

<div style="text-align:center;"><img src="./../../../images/codespaces-creation-log.png" alt=""></div>

=== "Manual"

## 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](https://github.com/ddev/ddev/releases) 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](https://github.com/FiloSottile/mkcert/releases) 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](configuring-browsers.md).