Craft CMS & DDEV: A Quick Start Guide (2022)

Oscar de la Hera Gomez
A flower that represents Craft CMS next to one that represents DDEV. Beneath them sits the text "Craft CMS & DDEV".

A step by step tutorial on installing DDEV and getting it working with a new or existing Craft CMS project.

With Nitro being retired by Pixel & Tonic, we needed to migrate to DDEV and wanted to share our process.

The following tutorial walks you through the process required to get DDEV installed on your machine. Once we cover that, it also informs you on how to get a new or existing Craft CMS project up and running.

The tutorial was built off the Fortrabbit guide & the Craft CMS official quick start guide which can be found in the link below. Please consult them for any questions that you might have on creating a new project or how DDEV functions compared

Step One: Install Homebrew

A screenshot of the Homebrew website.

We will use Homebrew to install DDEV. Make sure that the Homebrew package manager is installed on your system, using the link below.

Step Two: Install & Open Docker

A screenshot of Terminal showing you how to run the line written below to install docker.

DDEV works with Docker, which must be both installed and open for the DDEV installation to work.

Install Docker Desktop

brew cask install docker

Open Docker App

open /Applications/

Step Three: Install DDEV

A screenshot of Terminal showing you the line described below that installs DDEV and the required libraries.

After making sure that the Docker app is open and has been configured, install DDEV using the following line in terminal.

This will install DDEV and the libraries needed to install it.

brew tap drud/ddev && brew install ddev

Congratulations, you have successfully installed DDEV. The next steps are centered around making DDEV work with an existing Craft CMS project.

If by chance you're looking to start a new project, run the following command line in Terminal in the directory that you wish to create a folder with a new Craft CMS project:

composer create-project craftcms/craft

If you are new to Craft CMS, follow their installation guide provided in the link below.

Step Four: Make the Craft CMS project the current directory

A screenshot of Terminal showing you how to set the current directory.

In terminal set the current directory to that of the Craft CMS project that you wish to run with DDEV.

Step Five: Configure DDEV

A screenshot of Terminal showing you how to configure DDEV to your Craft CMS project. The line is provided below.

Run the following command in terminal:

ddev config

Please note that the default docroot is web and the project type is php for Craft CMS. This implies that you can press enter to each question that is asked, as it is the default answer.

Step Six: Update DDEV config.yml

A screenshot of Visual Studio Code (VSCode) with the DDEV Config.yaml file.

Under the newly created .ddev folder, modify your config.yaml to your needs. Crafts CMS's suggestions are the following:

  • Set php_version to whichever you need. (More in config.yaml’s comments.)
  • The database type can be mariadb, mysql, or postgres with a corresponding version.
  • Use additional_hostnames for other * domain names you’d like to use, or additional_fqdns for other custom domain names.

In our case, we updated the settings to take a mysql database to match version 8.0 (highest version allowed by DDEV) and subsequently running the following commands in Terminal:

ddev config --database=mariadb:10.4

Followed by

ddev debug migrate-database mysql:8.0

Step Seven: Start DDEV

A screenshot of Terminal showing you how to start Craft CMS using DDEV.

Run the following command in terminal:

ddev start

Step Eight: Run DDEV describe

A screenshot of Terminal showing you how to get the details of your DDEV instance. The line is provided below.

Run the following command in terminal:

ddev describe

Step Nine: Update your .env

A screenshot that demonstrates the Craft CMS environment variables and the Terminal DDEV describe side by side, along with the changes that were made to ease your understanding. Key elements here are to update  all the DB_ parameters.

Update your Craft CMS .env to match the details of the ddev describe.

Step Ten: Add .ddev to gitignore

A screenshot of the updated gitignore to ignore the .ddev folder.

To avoid your project checking in a lot of unnecessary changes, add the .ddev folder to your gitignore.

Step Eleven: Import Database

A screenshot of Terminal showing you the line that you need to run to import a DB into Craft CMS using DDEV. The line is provided below.

Replace YOUR_DB_PATH, with the path of a dump of your existing database and run the following command in terminal:

ddev import-db --src=YOUR_DB_PATH.sql

Step Eleven: Go to your local website

A screenshot of our Craft CMS running locally through a browser using DDEV.

Copy the Craft CMS website URL found in the ddev describe and paste it into your browser.

Any Questions?

We are actively looking for feedback on how to improve this resource. Please send us a note to with any thoughts or feedback you may have.

delasign logo

Book a Free Consultation.

An icon of an email.

Click here to email us.

Fill in the details below to book a free consultation or to let us know about something else. Whatever it is, we are here to help.

How can we help you ?

Contact Details