You’ll need a Docker provider on your system before you can install DDEV.
Install one of the supported Docker providers. OrbStack is the easiest to set up.
OrbStack is a new 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.
- Install OrbStack with
brew install orbstackor download it directly.
- Run the OrbStack app (from Applications) to finish setup, choosing “Docker” as the option. Answer any prompts to allow OrbStack access.
docker helpto make sure you’ve got the Docker client installed. If you get an error, install it with Homebrew by running
brew install docker.
- Install Colima with
brew install colima.
- Start Colima with 4 CPUs, 6GB memory, 100GB storage, and Cloudflare DNS, adjusting as needed:
--vm-type=qemuflag as it doesn’t work on older OS versions.)
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.
When your computer restarts, you’ll need to
colima start again. If you prefer to start Colima automatically on reboot, use
brew services start colima in Colima version 0.6+ to configure auto-start.
Colima disk allocation
In Colima versions starting with 0.5.4 you can increase—but not decrease—the disk allocation by editing
~/.colima/default/colima.yaml to change the
disk setting to a higher value. For example,
disk: 200 will increase allocation to 200 gigabytes. Then
colima restart will result in the new disk allocation.
Docker contexts let the Docker client point at the right Docker server
Colima activates its own Docker context to prevent conflicts with Docker Desktop. If you run
docker context ls, you’ll see a list of available contexts where the currently-active one is indicated with a
*—which will be
colima after you’ve started it. You can change to the default (Docker Desktop) with
docker context use default or change back with
docker context use colima. This means you can run Docker Desktop and Colima at the same time, but be mindful of which context you’re pointing at!
Colima can only work in your home directory unless you do further configuration
By default, Colima only mounts your home directory, so it’s easiest to use it in a subdirectory there. See the
~/.colima/default/colima.yaml for more information, or notes in colima.yaml.
Docker Desktop for Mac¶
Docker Desktop for Mac can be installed via Homebrew (
brew install --cask docker) or can be downloaded from docker.com. It has long been supported by DDEV and has extensive automated testing.
If you get messages like
Ports are not available... exposing port failed... is vmnetd running? it means you need to check the “Allow privileged port mapping (requires password)” checkbox in the “Advanced” section of the Docker Desktop configuration. You may have to stop and restart Docker Desktop.
Rancher Desktop is another free and open-source Docker provider. Install from Rancher Desktop.io. It has automated testing with DDEV. When installing, choose only the Docker option and turn off Kubernetes.
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?.
Avoid Docker Desktop for Linux
Current releases of Docker Desktop for Linux are not usable with DDEV for a number of reasons, and also exhibit some of the problems Docker Desktop has on other platforms. Please use the normal
docker-ce installation described here.
Docker installation on Linux depends on what flavor you’re using. It’s best to use your native package repository (
Linux installation absolutely requires adding your Linux user to the
docker group, and configuring the Docker daemon to start at boot. See Post-installation steps for Linux.
sudo with the
docker command. If you find yourself needing it, you haven’t finished the installation. You also shouldn’t use
ddev unless it’s specifically for the
ddev hostname command.
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.
If you’re working inside WSL2, which we recommend, you can install Docker Engine (docker-ce) inside of it. Otherwise, you can install Docker Desktop, which works with both traditional Windows and WSL2.
Docker CE Inside Windows WSL2¶
Many have moved away from using Docker Desktop in favor of the Docker-provided open-source
docker-ce package inside WSL2.
The instructions for DDEV Installation in WSL2 include Docker CE setup and a script that does almost all the work. Please use those.
Docker Desktop for Windows¶
Docker Desktop for Windows can be downloaded via Chocolatey with
choco install docker-desktop or it can be downloaded from docker.com. It has extensive automated testing with DDEV, and works with DDEV both on traditional Windows and in WSL2.
See WSL2 DDEV Installation for help installing DDEV with Docker Desktop on WSL2.
Alternate Docker Providers¶
There are a number of alternate Docker providers that can be used with DDEV.
Testing and Troubleshooting Your Docker Installation¶
Docker needs to be able to do a few things for DDEV to work:
- Mount the project code directory, typically a subdirectory of your home folder, from the host into the container.
- Access TCP ports on the host to serve HTTP and HTTPS. These are ports 80 and 443 by default, but they can be changed on a per-project basis.
We can use a single Docker command to make sure Docker is set up to do what we want:
In your project directory run the following (using Git Bash if you’re on Windows!):
The result should be a list of the files in your project directory.
If you get an error or don’t see the contents of your project directory, you’ll need to troubleshoot further:
- For a “port is already allocated” error, see the Troubleshooting page.
- “invalid mount config for type “bind”: bind mount source path does not exist: [some path]” means the filesystem isn’t successfully shared into the Docker container.
- If you’re seeing “The path (…) is not shared and is not known to Docker”, find File sharing in your Docker settings make sure the appropriate path or drive is included.
- “Error response from daemon: Get registry-1.docker.io/v2/” may mean Docker isn’t running or you don’t have internet access. Try starting or restarting Docker, and confirm you have a working internet connection.
- If you’re seeing “403 authentication required” trying to
ddev start, run
docker logoutand try again. Docker authentication is not required for any normal DDEV action.