Install TYPO3 with DDEV - in 8 Simple Steps

Before installing TYPO3, confirm that Docker and DDEV are correctly installed and running on your system. Verifying your environment in advance helps prevent installation failures, container startup issues, and configuration errors later in the process.

Verify Docker Installation

Check that Docker is installed, running, and accessible from your command line.

Run:

docker --version

You should see the installed Docker version. If the command is not recognized or returns an error, ensure Docker Desktop (Windows/macOS) or Docker Engine (Linux) is properly installed and running.

To confirm the Docker service is active, you can also run:

docker info

This command displays system-level details about the Docker environment. If Docker is not running, start it before proceeding.

Verify DDEV Installation

Next, confirm that DDEV is installed and functioning correctly.

Run:

ddev --version

This should return the installed DDEV version number. If not, install DDEV using the official installation instructions for your platform.

You can also test whether DDEV can communicate with Docker by running:

ddev poweroff

This command stops any running DDEV projects and verifies that DDEV can control Docker containers successfully.

Once both Docker and DDEV are verified, your system is ready to proceed with the TYPO3 installation using DDEV.

Check Available Ports & Running Containers

Before starting your TYPO3 project, ensure that the required network ports are free and no conflicting containers are already running. Port conflicts are a common cause of startup failures in Docker-based environments.

DDEV typically uses ports 80 (HTTP) and 443 (HTTPS) for routing local projects. If another service (such as Apache, Nginx, IIS, or another Docker container) is already using these ports, your environment may fail to start.

Check for Running Docker Containers

List active containers:

docker ps

If you see containers using web server images or occupying important ports, stop them before proceeding.

To stop all running containers (if safe to do so):

docker stop $(docker ps -q)

Check Port Usage on Your System

Verify whether ports 80 or 443 are already in use.

On Linux/macOS:

lsof -i :80

lsof -i :443

On Windows (PowerShell):

netstat -ano | findstr :80

netstat -ano | findstr :443

If another application is using these ports, stop or reconfigure that service before starting DDEV.

Stop Existing DDEV Projects (If Any)

If you previously ran other DDEV projects, shut them down to avoid conflicts:

ddev poweroff

This stops all running DDEV environments on your machine.

Ensuring that required ports are available and no conflicting containers are active will help your TYPO3 DDEV setup start cleanly and reliably.

For new TYPO3 installations, it is recommended to use the latest Long-Term Support (LTS) version available. LTS releases provide several years of security updates, bug fixes, and compatibility improvements, making them the safest and most stable choice for production and long-term development projects.

As of now, TYPO3 v13 LTS is the preferred option for new projects because it offers modern features, improved performance, and extended support coverage.

Why Choose the Latest LTS Version?

• Long Support Window: Receive regular security and maintenance updates for years.
• Modern Technology Stack: Supports current PHP versions and contemporary development practices.
• Better Performance & Security: Includes optimizations and hardened security features.
• Future-Proof Development: Reduces the need for near-term upgrades.
• Extension Compatibility: Most actively maintained extensions target the latest LTS versions.

Older versions (such as ELTS releases) are typically used only for maintaining legacy systems that cannot be upgraded immediately.

When creating a new TYPO3 project with DDEV, selecting the latest LTS version ensures the most reliable foundation for development, testing, and deployment.

Before installing TYPO3, ensure that the required tools are installed and functioning correctly on your system. This tutorial assumes a local development setup using Docker and the DDEV CLI.

To follow along, you will need:

• Docker installed and running
  • Docker Desktop for Windows or macOS
  • Docker Engine for Linux
• DDEV CLI installed

Install DDEV (If Not Already Installed)

You can install DDEV using the official installation script:

curl -fsSL ddev.com/install.sh | bash

Alternatively, download the version appropriate for your operating system from the official DDEV installation guide.

Verify Installation

After installing Docker and DDEV, confirm that both tools are available and working:

docker --version

ddev --version

These commands should display the installed version numbers. If both return valid outputs and Docker is running, your environment is ready for the TYPO3 DDEV setup.

TYPO3 projects can be installed using two different approaches: the modern Composer-based method and the older Classic (legacy) installation. Understanding the differences helps you choose the right setup for your project and development workflow.

Composer-Based Installation (Recommended)

Composer is the standard dependency manager for modern TYPO3 projects. In this approach, TYPO3 core packages and extensions are installed and managed through Composer, providing better control over versions and updates.

Key characteristics:

• TYPO3 core installed as Composer packages
• Dependencies managed automatically
• Easier upgrades and maintenance
• Supports modern development workflows and CI/CD
• Recommended for new projects and team environments

This method is fully supported by DDEV and aligns with current TYPO3 best practices.

Classic / Legacy Installation

The Classic installation method involves downloading TYPO3 as a standalone package (for example, from the TYPO3 website) and placing it directly in the web directory without using Composer.

Typical use cases:

• Maintaining older or legacy projects
• Environments where Composer is not used
• Quick evaluations of TYPO3 without dependency management

While still functional, this approach makes updates, extension management, and long-term maintenance more difficult compared to Composer-based setups.

Which Method Should You Choose?

• Choose Composer-based installation for new projects, professional development workflows, and long-term maintainability.
• Use Classic installation only when working with legacy systems or when Composer cannot be used.

For most modern TYPO3 projects running in DDEV, the Composer-based method is the recommended and future-proof option.

Start by creating a new folder for your TYPO3 project and navigating into it. This directory will contain your project files and the DDEV configuration.

mkdir my-typo3-project

cd my-typo3-project

For a fresh installation, this folder can be empty. DDEV will generate the necessary configuration and environment files during setup.

Once inside your project directory, run the configuration command:

ddev config

DDEV will prompt you for several project settings and then create a hidden .ddev/ folder containing essential configuration files such as:

• config.yaml — Main project configuration
• docker-compose.*.yaml — Optional service overrides

These files define how your TYPO3 environment will run inside Docker.

Project Name

Specify a project name (for example, my-typo3-project). This name is used by DDEV to identify the project and generate the local domain.

Docroot Configuration

Set the document root to the directory that should be served by the web server. For modern TYPO3 Composer-based installations, this is typically:

public

Ensure the docroot matches the folder where TYPO3’s public web files will reside. An incorrect docroot can lead to 404 errors or a non-functional site.

Note: If you are working with an existing TYPO3 project, verify the correct web root (for example, public/, web/, or another custom directory) before proceeding.

Project Type Selection

When prompted for the project type, choose:

typo3

Selecting the TYPO3 project type enables optimized default settings tailored for TYPO3 development, including appropriate web server configuration and environment variables.

After completing the prompts, DDEV generates the .ddev/ configuration directory. Your project is now ready for the next step: starting the environment and installing TYPO3.

Once DDEV is configured for your project, you can install TYPO3 using Composer. Running Composer inside the container ensures the correct PHP version and dependencies are used, matching your TYPO3 requirements.

Start the DDEV Environment

Initialize the local development environment:

ddev start

This command launches the required Docker containers, including:

• Web container
• Database container (MariaDB)
• Supporting services

After startup, your project environment is ready to accept commands and serve the application.

Access the Web Container

Enter the running web container to execute Composer commands within the configured environment:

ddev ssh

You will be placed inside the container shell, typically at:

/var/www/html

All subsequent installation commands should be executed from here.

Create the TYPO3 Project with Composer

Use Composer to download and install the TYPO3 base distribution:

composer create-project typo3/cms-base-distribution public

This installs TYPO3 into the public/ directory, which is the recommended document root for modern Composer-based setups.

Alternative:
If your project uses a different structure, replace public with your configured docroot folder.

This process downloads TYPO3 core files, required dependencies, and default project structure.

File Ownership & Permissions

DDEV typically manages file permissions automatically. However, if you encounter permission issues (for example, inaccessible files or write errors), adjust ownership from outside the container:

exit
ddev exec chown -R www-data:www-data /var/www/html/public

Ensuring correct ownership allows the web server to read and write files properly, which is essential for TYPO3 installation and operation.

After completing these steps, TYPO3 core files will be installed and ready for configuration through the Install Tool.

After installing TYPO3, complete the setup using the browser-based Installation Wizard.

Open your project in a browser:

ddev launch

This opens your local site (for example: https:// my-typo3-project.ddev.site).

If TYPO3 is installed correctly, the Install Tool will appear automatically.

DDEV provides database credentials via environment variables. Use the default values if prompted:

• Host: db
• Database name: db
• Username: db
• Password: db

Create the administrator account, finalize the setup, and your local TYPO3 instance will be ready.

Note: If you encounter a 404 error or missing directory message, verify that the docroot in .ddev/config.yaml is correct.