Skip to content

DDEV Installation

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

Installing and upgrading DDEV are nearly the same thing, because you're upgrading the ddev binary that talks with Docker. You can update this file like other software on your system, whether it’s with a package manager or traditional installer.

macOS

Homebrew

Homebrew is the easiest way to install and upgrade DDEV:

brew install drud/ddev/ddev
brew upgrade ddev

As a one-time initialization, run

mkcert -install

Install Script

Tip

The install script works on macOS, Linux, and Windows WSL2.

Run the install script to install or update DDEV. It downloads, verifies, and sets up the ddev binary:

curl -fsSL https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh | bash

You can include a -s <version> argument to install a specific release or a prerelease version:

curl -fsSL https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh | bash -s v1.19.5

Linux

Debian/Ubuntu

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

curl https://apt.fury.io/drud/gpg.key | sudo apt-key add -
echo "deb https://apt.fury.io/drud/ * *" | sudo tee -a /etc/apt/sources.list.d/ddev.list
sudo apt update && sudo apt install -y ddev

Update with your usual commands:

sudo apt update && sudo apt upgrade

Removing Previous Install Methods

If you previously used DDEV’s install script, you can remove that version:

sudo rm -f /usr/local/bin/ddev /usr/local/bin/mkcert /usr/local/bin/*ddev_nfs_setup.sh

If you previously installed DDEV with Homebrew, you can run brew unlink ddev to get rid of the Homebrew version.

Fedora, Red Hat, etc.

echo '[ddev]
name=DDEV Repo
baseurl=https://yum.fury.io/drud/
enabled=1
gpgcheck=0' | sudo tee -a /etc/yum.repos.d/ddev.repo

sudo dnf install --refresh ddev

In the future you can update as usual using sudo dnf upgrade ddev. (Signed repository support will be added in the near future.)

Arch Linux

For Arch-based systems including Arch Linux, EndeavourOS and Manjaro we maintain the ddev-bin package in AUR. To install use yay -S ddev or whatever other AUR tool you use; to upgrade yay -Syu ddev.

As a one-time initialization, run mkcert -install.

Alternate Linux Install Methods

You can also use two macOS install methods to install or update DDEV on Linux: Homebrew (only on AMD64 computers) and the standalone install script.

Windows WSL2

Windows WSL2 is a fantastic way to run DDEV and your web components. It’s Linux, which means a different experience for many Windows users. It’s Ubuntu Linux by default as described here, so it’s worth taking a little time to explore how Ubuntu and Bash work, including standard system commands and installation and upgrade procedures.

WSL2 is the recommended installation method for all Windows users.

Using WSL2 to install and run DDEV is not the same as using Docker Desktop’s WSL2 engine, which itself runs in WSL2, but can serve applications running in both traditional WIndows and inside WSL2.

All Windows 10/11 editions (including Windows 10 Home) support WSL2. If you’re already familiar with DDEV on Windows, you might have been using NFS for better filesystem performance. You won't need NFS anymore once you switch to WSL2, since it provides awesome filesystem performance out of the box.

The WSL2 install process involves:

  • Installing Chocolatey package manager (optional).
  • One time initialization of mkcert.
  • Installing WSL2 and installing a distro like Ubuntu.
  • Installing or upgrading to the latest Docker Desktop for Windows with WSL2 enabled.
  • Installing DDEV inside your distro.

We’ll walk through these in more detail. You may prefer other techniques of installation or may not need some steps, but this is the full recipe:

  1. Chocolatey: We recommend using Chocolatey for installing required Windows apps like mkcert. In an administrative PowerShell, Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
  2. In an administrative PowerShell: choco install -y mkcert
  3. In an administrative PowerShell, run mkcert -install and answer the prompt allowing the installation of the Certificate Authority.
  4. In an administrative PowerShell, run the command setx CAROOT "$(mkcert -CAROOT)"; If ($Env:WSLENV -notlike "*CAROOT/up:*") { setx WSLENV "CAROOT/up:$Env:WSLENV" }. This will set WSL2 to use the Certificate Authority installed on the Windows side.
  5. In administrative PowerShell, run the command wsl --install. This will install WSL2 and Ubuntu for you. Reboot when this is done.
  6. Docker Desktop for Windows: If you already have the latest Docker Desktop, configure it in the General Settings to use the WSL2-based engine. Otherwise install the latest Docker Desktop for Windows and select the WSL2-based engine (not legacy Hyper-V) when installing. Install via Chocolatey with choco install docker-desktop or it can be downloaded from desktop.docker.com. Start Docker. It may prompt you to log out and log in again, or reboot.
  7. Go to Docker Desktop’s SettingsResourcesWSL integrationenable integration for your distro. Now docker commands will be available from within your WSL2 distro.
  8. Double-check in PowerShell: wsl -l -v should show three distros, and your Ubuntu should be the default. All three should be WSL version 2.
  9. Double-check in Ubuntu (or your distro): echo $CAROOT should show something like /mnt/c/Users/<you>/AppData/Local/mkcert
  10. Check that Docker is working inside Ubuntu (or your distro): docker ps
  11. Optional: If you prefer to use the traditional Windows DDEV instead of working inside WSL2, install it with choco install -y ddev. The Windows DDEV works fine with the WSL2-based Docker engine. However, the WSL2 DDEV setup is vastly preferable and at least 10 times as fast. Support for the traditional Windows approach will eventually be dropped.
  12. Open the WSL2 terminal, for example Ubuntu from the Windows start menu.
  13. Install DDEV using

    curl https://apt.fury.io/drud/gpg.key | sudo apt-key add -
    echo "deb https://apt.fury.io/drud/ * *" | sudo tee -a /etc/apt/sources.list.d/ddev.list
    sudo apt update && sudo apt install -y ddev
    
  14. In WSL2 run mkcert -install.

That’s it! You have now installed DDEV on WSL2. If you’re using WSL2 for DDEV (recommended), remember to run all ddev commands inside the WSL2 distro.

To upgrade DDEV in WSL2 Ubuntu, use apt upgrade ddev as described in the Linux installation section.

Projects go in /home, not on the Windows filesystem

Make sure you put your projects in the Linux filesystem (e.g. /home/<your_username>), not in the Windows filesystem (/mnt/c), because you’ll get vastly superior performance on the Linux filesystem. You will be very unhappy if you put your project in /mnt/c.

Path to certificates

Note the prompt Installing to the system store is not yet supported on this Linux, which can be a simple result of not having /usr/sbin in the path so that /usr/sbin/update-ca-certificates can be found.)

Traditional Windows

DDEV does work fine on the Windows side, although it’s quite a bit slower than WSL2 by default. Good results have been reported by users who enabled Mutagen.

  • If you use Chocolatey (recommended), you can run choco install ddev git from an administrative shell. Upgrades are just ddev poweroff && choco upgrade ddev.
  • A Windows installer is provided in each DDEV release (ddev_windows_installer.<version>.exe). Run that and it will do the full installation for you. Open a new Git Bash or PowerShell or cmd window and start using DDEV.
  • Most people interact with DDEV on Windows using Git Bash, part of the Windows Git suite. Although DDEV does work with cmd and PowerShell, it's more at home in Bash. You can install it with Chocolatey using choco install -y git.
  • For performance, many users enable Mutagen, ddev config global --mutagen-enabled (global) or ddev config --mutagen-enabled just for one project.

Windows Firefox Trusted CA

The mkcert -install step on Windows isn’t enough for Firefox. You need to add the created root certificate authority to the security configuration yourself:

  • Run mkcert -install (you can use the shortcut from the Start Menu for that)
  • Run mkcert -CAROOT to see the local folder used for the newly-created root certificate authority
  • Open Firefox Preferences (about:preferences#privacy)
  • Enter “certificates” into the search box on the top
  • Click View Certificates...
  • Select Authorities tab
  • Click to Import...
  • Navigate to the folder where your root certificate authority was stored
  • Select the rootCA.pem file
  • Click to Open

You should now see your CA under mkcert development CA.

Gitpod

DDEV is fully supported in Gitpod, where you don’t have to install anything at all.

Choose any of the following methods to launch your project:

  1. Open any repository using Gitpod, run brew install drud/ddev/ddev, and use DDEV!
    • You can install your web app there, or import a database.
    • You may want to implement one of the ddev pull provider integrations to pull from a hosting provider or an upstream source.
  2. Use the ddev-gitpod-launcher form to launch a repository.
    You’ll provide a source repository and click a button to open a newly-established environment. You can specify a companion artifacts repository and automatically load db.sql.gz and files.tgz from it. (More details in the repository’s README.)
  3. Save the following link to your bookmark bar: Open in ddev-gitpod.
    It’s easiest to drag the link into your bookmarks. When you’re on a Git repository, click the bookmark to open it with DDEV in Gitpod. It does the same thing as the second option, but it works on non-Chrome browsers and you can use native browser keyboard shortcuts.

It can be complicated to get private databases and files into Gitpod, so in addition to the launchers, the git provider example demonstrates pulling a database and files without complex setup or permissions. This was created explicitly for Gitpod integration, because in Gitpod you typically already have access to private Git repositories, which are a fine place to put a starter database and files. Although ddev-gitpod-launcher and the web extension provide the capability, you may want to integrate a Git provider—or one of the other providers—for each project.

Manual

DDEV is a single executable, so installation on any OS is a matter of copying the a ddev binary 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.


Last update: October 7, 2022