Set up your environment

Every page in these docs assumes the same local toolchain: DDEV running PHP 8.3 and a database in containers, Composer managing the codebase, and Drush for site control. This page stands that toolchain up. You end with a complete, Composer-managed Drupal 11 codebase that is ready to install.

Goal

A working local development environment and a Drupal 11 project directory, but not yet an installed site. Installing the site is the next page, Install Drupal core. If you are joining a team that already has a Drupal codebase in version control, skim the steps and then follow the variation for existing projects instead.

Prerequisites

• A machine running macOS, Linux, or Windows with WSL2.
• Docker or an equivalent container runtime, which DDEV runs on.
• Familiarity with a terminal. No PHP or Drupal knowledge is needed yet.

You do not need to install PHP, Composer, a web server, or a database yourself. DDEV provides all of them inside its containers, pinned to versions that match what Drupal 11 needs: Drupal core requires PHP 8.3.0 or higher, and DDEV’s drupal11 project type defaults to a compatible PHP version.

Steps

Install DDEV

Follow the DDEV installation instructions for your operating system. Confirm it works:

ddev version

Create the project directory

mkdir my-site && cd my-site
ddev config --project-type=drupal11 --docroot=web

ddev config writes a .ddev/config.yaml describing the project. The drupal11 project type tells DDEV to provision a PHP version and database that Drupal 11 supports, and to generate Drupal-specific settings later. The --docroot=web flag matches the layout that Drupal’s Composer project template uses: the web server serves web/, while composer.json and vendor/ stay one level above it, outside the web root.

Start the containers

ddev start

The first start downloads container images, so it takes a few minutes. When it finishes, DDEV prints the project URL (something like https://my-site.ddev.site). There is nothing to serve yet.

Create the Drupal codebase

ddev composer create-project drupal/recommended-project
ddev composer require drush/drush

drupal/recommended-project is the official Composer template for Drupal sites. It gives you a composer.json whose key dependencies are:

• drupal/core-recommended: Drupal core plus its dependencies pinned to the exact versions core was tested with.
• drupal/core-composer-scaffold: a Composer plugin that copies files Drupal needs in the web root (index.php, .htaccess, robots.txt, sites/default/default.settings.php) into web/ on every install and update.
• composer/installers: routes Drupal packages to the right directories, so a module lands in web/modules/contrib/ instead of vendor/.

Drush is not part of core, which is why you add drush/drush yourself. It is the command-line tool you will use for cache rebuilds, one-time logins, and configuration work throughout these docs; Essential tools covers it in depth.

If you plan to write or run tests, add the development dependencies as well:

ddev composer require --dev drupal/core-dev

Your project directory now looks like this:

• Directorymy-site/

  • Directory.ddev/

    • config.yaml
  • composer.json
  • composer.lock
  • Directoryvendor/

    • …
  • Directoryweb/

    • Directorycore/

      • …
    • Directorymodules/

      • …
    • Directorythemes/

      • …
    • Directoryprofiles/

      • …
    • Directorysites/

      • Directorydefault/

        • default.settings.php
        • settings.php
        • settings.ddev.php
      • example.settings.local.php
    • index.php

Anatomy of a Drupal project explains what each of these directories is for and, more importantly, which of them are yours to edit.

Know your settings files

Three PHP files control how this codebase connects to its environment. You do not need to touch them today, but you should know what they are before the installer reads them:

• web/sites/default/settings.php: the site’s main settings file. It holds the database credentials, the trusted host patterns, and the config sync directory (where the site’s configuration is exported to YAML for version control, covered in configuration management). DDEV has already created it from default.settings.php, together with a settings.ddev.php next to it that holds the container database credentials. DDEV adds the include for settings.ddev.php at the bottom of settings.php, which is why you never type database credentials locally.
• web/sites/default/settings.local.php: optional per-developer overrides that stay out of version control. Core ships a documented starting point at web/sites/example.settings.local.php that turns on verbose error output and disables CSS and JavaScript aggregation. The last lines of default.settings.php contain a commented-out block that loads it. Activating it is the first step of Debug a Drupal site, so leave it for now.
• web/sites/development.services.yml: extra service container definitions for development, loaded only when settings.local.php activates them. This is where the null cache backend and the cacheability debug headers come from.

The pattern to remember: settings.php is for the site, settings.local.php is for you.

Verify

Run:

ddev describe

You should see the project listed as running, with its URL, database, and PHP version. Then confirm the PHP version inside the web container meets Drupal 11’s minimum of PHP 8.3:

ddev exec php -v

Finally, check that the codebase is in place: web/core/ exists and ddev exec vendor/bin/drush --version prints a Drush version. A browser visit to the project URL shows a Drupal error page or the installer, which is expected: the codebase exists, the site does not. Continue with Install Drupal core.

Variations

Join an existing project

Most developers inherit a project rather than start one. The codebase comes from version control; the database and uploaded files come from a teammate or a hosting environment, because neither is stored in git.

1. Clone the repository and enter it. If the team committed a .ddev/ directory, skip ddev config; the project is already described. Otherwise run ddev config --project-type=drupal11 --docroot=web (adjust the docroot if the repository differs).

2. Start the environment and install dependencies. vendor/ and web/core/ are never committed; Composer rebuilds them from composer.lock:

   ddev start
   ddev composer install

3. Import a database dump from a teammate or your hosting platform:

   ddev import-db --file=site-backup.sql.gz

4. Import the user-uploaded files (everything under web/sites/default/files/), which are also not in git:

   ddev import-files --source=files-backup.tar.gz

   If you skip this step the site still works, but images and other uploads render as broken links. Some teams use a stage file proxy module instead of copying files; ask.

5. Rebuild caches and log in:

   ddev drush cache:rebuild
   ddev drush user:login

drush user:login (uli) prints a one-time login URL for the admin account, so you never need a password from the dump.

Work without DDEV

If you already maintain a native PHP stack, the only hard requirements are PHP 8.3 or higher with the extensions Drupal core lists in its composer.json, Composer 2, and a supported database. Create the codebase with composer create-project drupal/recommended-project my-site. The rest of these docs write commands in DDEV form (ddev drush ...); the Personalize control in the top bar switches them all to native form (and lets you set your docroot, project name, and site URL). For a zero-configuration throwaway site, core’s own quick-start command needs nothing but PHP and SQLite; see Install Drupal core.

Related

• Install Drupal core completes the setup with an installed site.
• Anatomy of a Drupal project maps every directory you created here.
• Essential tools covers Composer, Drush, and core’s own CLI day to day.
• Debug a Drupal site activates the local settings files you previewed above.