DDEV Projects

For all projects and the other run methods, see Projects.

If DDEV is not installed, the app tells you only if you had DDEV projects before. The DDEV Settings item in the sidebar shows when DDEV is installed or when you have DDEV projects.

When you have no DDEV projects, the app hides the controls that apply only to DDEV, for example the power icon that stops all projects.

The app shows the DDEV projects that DDEV already knows (ddev list). To add a project folder that DDEV does not know yet, drop it on the app window. See Import Projects.

Create a project

1. Click New Project in the top bar.
2. In step 1 of 2, What are you building?, select a stack: Laravel, Symfony, WordPress, Drupal or Other PHP. You can also select Clone a repository or Empty folder.
   • Version (Drupal) or Type (Other PHP): The DDEV project type, for example Drupal 11, Craft CMS or Magento 2.
   • Description: A short description, shown in the project list.
   • Name: The project name. It must be safe for a hostname.
   • Folder: The project folder. The app creates it if it does not exist.
3. Click Next, or press Enter.
4. In step 2 of 2, How do you run it?, select DDEV. DDEV is the default for PHP stacks.
5. Set the DDEV options on the Web and Database tabs. For example: TLD, PHP version, web server, Node.js version, Composer version, document root, Xdebug, and database type and version. For Clone a repository and Empty folder, also select the Project type.
6. Click Create Project.

The app checks that DDEV is installed. If DDEV is missing, step 2 shows a notice with an Install DDEV link and Check again, and Create Project is disabled.

To create a .NET, Node.js, Python, Go or Rust project, or a PHP project without DDEV, select a different run method in step 2. See Run methods.

Name follows Description, and Folder follows Name, until you edit them. The app remembers the last stack that you selected.

The app shows errors below the field. If Next is disabled, the footer shows the reason. The app blocks these values:

• The projects folder itself or your home folder as Folder.
• A Name that another project already uses.

The app shows a warning if the folder already has files or a .ddev folder.

To add a folder that has code but no DDEV configuration, set Folder to that folder.

Default versions

PHP version, Web server and Database are set to DDEV default. DDEV then selects the value for the project type. Select a version only if you need a specific one.

The other default values come from Preferences.

Laravel projects

The app creates Laravel projects with ddev composer create-project laravel/laravel. This is the DDEV quickstart. DDEV sets the database settings in .env.

Create from GitHub

1. In step 1, select Clone a repository.
2. Enter the Git repository URL, for example https://github.com/user/repo.git.
3. In step 2, select DDEV. DDEV is the default when it is installed. The app detects the Project type from the repository name.
4. Complete the other steps.

The app also checks that Git is installed.

You must have access to the repository. The Folder must be empty.

The app clones the repository into the folder. It then runs ddev start and ddev composer install. For Laravel, it also creates .env from .env.example and runs ddev artisan key:generate.

The app never runs scaffold commands on a cloned repository. If the clone fails, the app stops.

Progress

One notification shows the progress:

1. Configuring DDEV
2. Starting containers
3. Installing the framework, for example Installing Laravel
4. Ready

When the setup is complete, the app opens the project. The notification has Open site and Open folder.

If a step fails, the message shows the step, the exit code and the last line of output. The notification has Show output and Open folder.

Review the setup commands

To see the setup commands before they run, select Review the setup commands before they run in step 2. The Review setup commands dialog then opens. Edit the commands if necessary, then click Run.

TLD

ddev.site works with no setup. Other TLDs, for example .test, need entries in /etc/hosts. For these TLDs, DDEV can ask for your sudo password when a project starts or when you delete it.

Project page

The header of the project page has these buttons:

• New AI session: see AI Sessions.
• Start, or Stop and Restart when the project runs.
• Open: opens the primary URL in your browser.
• Share: shows when the project runs. With the ddev-share-cf add-on, it runs ddev share-cf in a headless terminal. Without the add-on, it shows the install command and a link to the Cloudflare Tunnel recipe.
• IDE: opens the project with IDE Command from Preferences → General.
• On / Off: turns Xdebug on or off. The menu next to it has IDE Configuration for VS Code and PhpStorm. See Xdebug.

Project tabs

A DDEV project has these tabs:

Tab	Details
Overview	Project details, Database, Services, remote server and Security cards
Terminal	Terminal
Remote SSH	Remote SSH
Files	Files
Git	Sub-tabs Changes and History (Git Changes), Issues and Actions (GitHub)
Scratchpad	Scratchpad
Logs	Logs
Health	Sub-tabs Security (Dependency Security) and Uptime (Uptime Monitoring)

To go to a tab, press ⌘ (Ctrl on Windows and Linux) and the tab number.

Each project keeps its last tab. It also keeps the sub-view in Git and Health.

Some tab labels show a status:

• Git: the number of added and removed lines, for example +12 −3. The projects sidebar shows the same numbers.
• Health: the number of vulnerabilities, in the color of the highest severity. A red dot shows when an uptime monitor is down.

Recipes at the right end of the tab bar opens the Recipes panel. The button shows a spinner while a recipe runs.

Overview

The Overview tab has two columns of cards. The left column has Project Information, Database and Remote server. The right column has Quick Actions, Security and Services.

• Project Information: Name, Type, PHP Version, Laravel Version (Laravel only), Web Server, Database, Router, GitHub and Created. With Traefik, click the router to open the Traefik dashboard. GitHub shows the repository as owner/repo. Click it to open the repository. Move the pointer over it to see the full URL and the copy button. When no URL is set, click the folder icon to find the repository from the Git remotes of the project.
• Quick Actions: Open Website, Open phpMyAdmin (when the service exists), Open Mailpit and Open Folder. Open Website opens the primary URL of the project, which DDEV sets (usually https://<name>.<tld>). Click the arrow beside it to see all HTTPS and HTTP URLs of the project, or to edit the additional hostnames.
• Database: the connection details and the additional databases. See Database.
• Services: a row for each DDEV service. See Services & Addons.
• Security: the result of the last dependency check. See The Security card.
• Remote server: the connection name, the key and the remote root. Click Open remote shell to open the Remote SSH tab. Click Edit connection, or Set up connection when there is no connection. See Remote SSH.

If the project fails to load, the tab shows Error Loading Project with the error. Only the Overview tab is then available.

Start, stop and restart

The project cards on the Projects page also have start and stop buttons.

To stop all projects (ddev poweroff), click the power icon in the top bar.

To control single services, use the Services card on the Overview tab. See Services and Add-ons.

Change the configuration

On the Overview tab, hover a value and click the edit icon. You can change:

• Name
• Type
• PHP version
• Additional FQDNs (Open Website › arrow › Edit hostnames)
• GitHub repository URL

For settings that apply to all projects, see Configuration.

Rename a project

To rename a DDEV project, the app exports the database, deletes the DDEV project, configures it with the new name, starts it and imports the database again. A notification shows the progress of each step until the rename is complete. When the rename is complete:

• If the project was open, it stays open with the new name, on the same tab.
• The terminal sessions and the Remote session of the old name close.

Hide projects

To hide a project, go to the Projects page and click the eye icon on the project card.

Hidden projects do not show on the dashboard or in the project switcher (⌘K on macOS, Ctrl+K on Windows and Linux). They also do not show when you press Ctrl+Tab to go to a recent project. The only exception is the project that is open now. To see hidden projects on the Projects page, click the Show hidden projects icon at the top of the page.

Dashboard

Recent Projects

This section shows the projects that you opened last, with the most recent first. If you did not open a project yet, it shows some of your projects, with the running projects first.

Each project card shows the Git changes of the project. If the project has unfinished AI sessions, the card shows a button to resume them. See AI Sessions.

Recent Activities

The activity log shows the recent actions that the app did, with a timestamp. Examples are project start and stop, project creation and deletion, configuration changes, and SSH, database and GitHub actions.

Commands Log

To see each ddev command that DevWorkspace Pro runs and its result, click Commands Log in the sidebar. It keeps its text when you leave the page and come back.

Delete a project

1. Go to the Projects page.
2. Click the delete icon on the project card.
3. Optional: select Also delete project folder from disk.

WARNING

The app runs ddev delete --omit-snapshot. This removes the DDEV project and its database, with no snapshot. Your project files stay on disk, unless you select Also delete project folder from disk. Back up the database first if you need it.

The app also closes the terminal sessions and the Remote SSH session of the project.