Welcome to this step-by-step guide to installing TYPO3 with DDEV for local development. In this tutorial, you’ll set up a fresh TYPO3 instance using Composer inside a Docker-based DDEV environment, resulting in a fast, reproducible setup that works consistently across machines.
This guide is designed for developers and teams who want a reliable local TYPO3 setup without manual configuration of PHP, web servers, or databases. Whether you’re starting a new project or preparing a clean development environment, DDEV streamlines the entire process.
Before you begin, make sure Docker and DDEV are installed and running on your system, as they are required for the installation.
If you’re looking to deploy TYPO3 on cloud platforms instead of locally, you can explore these guides:
Now, let’s walk through the TYPO3 DDEV setup step by step and get your local site up and running.
Short answer: To install TYPO3 with DDEV, open an empty folder and run ddev config --project-type=typo3 --docroot=public --php-version=8.4, ddev start, ddev composer create-project "typo3/cms-base-distribution:^14" and ddev typo3 setup. Then open the backend with ddev launch /typo3/. For TYPO3 v13 LTS, use ^13 instead of ^14.
Key takeaways
- TYPO3 v14 LTS (14.3) is recommended for new projects; v13.4 LTS is the version for existing projects.
- Both versions support PHP 8.2 to 8.5; the official TYPO3 DDEV tutorial uses PHP 8.4.
- Run Composer with
ddev composerfrom your computer;ddev sshis not needed for the install. ddev typo3 setupsets up TYPO3 in one command; the web installer still works with aFIRST_INSTALLfile.- On TYPO3 14.1 and later, the Camino default theme gives you a working demo site.
- DDEV runs on macOS (including Apple Silicon), Windows with WSL2 and Linux, with OrbStack, Docker Desktop, Rancher Desktop, Colima, Lima or Docker CE.
Tested with / valid for: TYPO3 v14.3 LTS and v13.4 LTS, commands checked against the current DDEV and TYPO3 documentation. Updated: November 2026
Updated 11 November 2026 | T3Planet editorial team
How do you install TYPO3 with DDEV? Quick start
These are the commands from the official TYPO3 and DDEV quick starts for a new TYPO3 installation with TYPO3 v14 LTS. Run them in an empty folder; Git or an IDE should not have created files there yet.
TYPO3 v14 LTS (recommended for new projects)
mkdir my-typo3-site && cd my-typo3-siteddev config --project-type=typo3 --docroot=public --php-version=8.4ddev startddev composer create-project "typo3/cms-base-distribution:^14"ddev composer require typo3/theme-caminoddev typo3 setup --server-type=other --driver=mysqli --host=db --port=3306 --dbname=db --username=db --password=db --create-site=https://my-typo3-site.ddev.siteddev launch /typo3/
The setup command asks for the admin user name, password, e-mail and project name. Your site then runs at https://my-typo3-site.ddev.site and the backend at /typo3/.
TYPO3 v13.4 LTS (existing projects)
Use the same steps with "typo3/cms-base-distribution:^13", skip the Camino theme (it was added in TYPO3 14.1) and run ddev typo3 setup without --create-site.
Which setup method should you use?
| Method | Works in | Best for | Caveat |
ddev typo3 setup (console) | v13.4, v14 | Fast, repeatable installs and scripts | Pass the DDEV database values (db/db/db, host db) |
Web installer (FIRST_INSTALL + /typo3/install.php) | v13.4, v14 | A guided setup in the browser | Create the public/FIRST_INSTALL file first |
| Camino default theme | v14.1 and later | A working demo site right after install | Not available in v13; customizable only in a limited way |
ddev ssh + composer inside the container | v13.4, v14 | Long interactive shell sessions | Not needed for the install; ddev composer runs from the host |
Sources: TYPO3 Getting Started: Installing TYPO3 with DDEV (v14), the same page for v13.4 and the DDEV CMS quickstarts.
Prerequisites: Docker (or another Docker provider) and DDEV must be installed and running before executing these commands.
What Is TYPO3?
TYPO3 is a free, open-source Content Management System (CMS) designed to help businesses and organizations create, manage, and grow their websites. Founded in 1997 by Kasper Skårhøj, TYPO3 has become one of the most widely used enterprise CMS platforms, particularly across Europe.
Built with PHP, TYPO3 uses TypoScript, a powerful configuration language that enables advanced customization and flexibility. It runs directly in your browser and delivers content using standard HTML and JavaScript, so no special client software is required.
TYPO3 is suitable for projects of all sizes. Whether you’re managing a small business website, a university portal, or a large enterprise platform, TYPO3 can scale to meet your requirements.
Why Developers, Marketers, and Agencies Choose TYPO3
TYPO3 is an open-source platform that grows with your project while maintaining stability and control. Key strengths include:
- Modularity: Build exactly what you need with a flexible extension ecosystem.
- Security & Stability: Long-Term Support (LTS) releases provide reliable updates and security patches for years.
- Scalability: Capable of supporting anything from small sites to complex global platforms.
- Community-Driven Development: A large international community continuously improves and maintains the system.
TYPO3 in Numbers
TYPO3 powers more than 500,000 active websites worldwide, making it a proven and trusted choice for enterprise-grade web projects.
Read more TYPO3 facts to explore its capabilities and real-world adoption.
Why Use TYPO3?
TYPO3 provides a robust set of enterprise-grade features designed for organizations that require flexibility, security, and long-term reliability. It supports complex website structures while remaining highly customizable through its extensive extension ecosystem.
Key advantages include:
- Granular User Roles & Permissions: Control access at a detailed level for editors, managers, and administrators.
- Multisite Management: Manage multiple websites from a single TYPO3 installation, ideal for enterprises and institutions.
- Extensibility: A large ecosystem of extensions enables you to add functionality without rebuilding core features.
- Scalability & Performance: Built to handle everything from small projects to large, high-traffic platforms.
- Long-Term Support: Regular LTS releases ensure stability, security updates, and predictable maintenance cycles.
TYPO3 is especially well suited for businesses, public institutions, and digital agencies that need a scalable CMS capable of supporting complex requirements over many years.
What do you need to run TYPO3 DDEV smoothly?
Before starting the TYPO3 installation with DDEV, ensure your system meets the necessary requirements. Running TYPO3 locally with DDEV depends on a containerized environment and a few essential tools working together.
The following components are required for a stable and efficient TYPO3 DDEV setup.
Docker
Docker is the foundation of the TYPO3 Docker setup. It provides isolated containers that run TYPO3 independently from your host system, preventing version conflicts and ensuring consistent behavior across different machines and team members’ environments.
DDEV
DDEV is a local development tool built on Docker that simplifies project setup and management. With a small set of commands, it provisions a complete TYPO3 development environment, including web server, PHP, and database services.
Operating System
DDEV supports Windows, macOS, and Linux. It needs a Docker provider: on macOS OrbStack, Lima, Docker Desktop, Rancher Desktop or Colima; on Windows WSL2 with Docker CE inside WSL2, Docker Desktop or Rancher Desktop; on Linux Docker CE from the official Docker repository (DDEV Docker installation).
PHP Compatibility
The required PHP version depends on the TYPO3 version you plan to install. DDEV allows you to specify the PHP version in the project configuration, making it easy to match TYPO3’s system requirements without manual PHP installation. TYPO3 v14 and v13.4 both support PHP 8.2, 8.3, 8.4 and 8.5 (get.typo3.org).
Database (MySQL/MariaDB)
TYPO3 requires a database to store content, configuration, and user data. DDEV automatically provisions a MariaDB database (fully compatible with MySQL), eliminating the need for manual database setup.
SSH Access
An SSH interface is used to interact with the running containers. Commands such as ddev ssh allow you to access the web container, manage files, and run Composer directly within the TYPO3 environment.
Composer & Git
Composer is required to install TYPO3 packages and manage dependencies in modern TYPO3 projects. Git is recommended for version control, especially when collaborating with a team or maintaining a project repository.
You can now proceed with the step-by-step guide to install TYPO3 using DDEV.
System Requirements & Environment Notes
To run TYPO3 with DDEV efficiently, your system should meet certain hardware and platform conditions. While TYPO3 can run on modest setups, containerized development with Docker performs significantly better with adequate resources and proper OS configuration.
Recommended Hardware Resources
For a smooth local development experience, especially when running Docker containers, the following minimum specifications are recommended:
- RAM: At least 8 GB (16 GB recommended for larger projects)
- CPU: Modern multi-core processor (Intel i5 / AMD Ryzen 5 or higher)
- Disk Space: Minimum 10–20 GB free storage for containers, images, and project files
- SSD Storage: Strongly recommended for faster container performance and file operations
Insufficient resources may lead to slow container startup times, sluggish backend performance, or build failures.
OS-Specific Considerations (Windows, macOS, Linux)
DDEV and Docker support all major desktop operating systems, but setup details vary by platform:
- Windows: Install WSL2 first. DDEV recommends Docker CE inside WSL2; Docker Desktop and Rancher Desktop also work. The DDEV Windows installer can set up Docker CE inside WSL2 for you.
- macOS: DDEV documents OrbStack as the recommended and fastest provider (commercial), with Lima, Rancher Desktop and Colima as free, open-source alternatives and Docker Desktop as a further option. Lima and Colima only work with projects in your home directory unless you configure more mounts.
- Linux: Typically offers the best performance because Docker runs natively. Ensure your user has permission to run Docker commands without sudo.
Regardless of the OS, verify that virtualization is enabled in your system BIOS/UEFI settings.
Apple Silicon & WSL2 Notes
Modern hardware platforms require a few additional considerations:
- Apple Silicon: Supported by DDEV and all macOS providers listed above. Keep DDEV and your Docker provider up to date, because older custom images may not be built for ARM.
- Windows WSL2: Essential for running Docker efficiently on Windows. Ensure your Linux distribution is updated and integrated with Docker Desktop.
- Cross-Architecture Projects: When collaborating with teams using different hardware architectures, container builds may take longer on first run but will remain consistent afterward.
Meeting these requirements ensures a stable, fast, and reproducible TYPO3 development environment with DDEV.
Validate Your Setup Before Installation
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.
For a full check of Docker, network, DNS and HTTPS certificates, run ddev utility diagnose (DDEV command reference).
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 :80lsof -i :443
On Windows (PowerShell):
netstat -ano | findstr :80netstat -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.
Why run DDEV on TYPO3?
Using DDEV with TYPO3 provides a modern, container-based approach to local development that eliminates manual server configuration and environment inconsistencies.
Instead of installing and maintaining PHP, web servers, and databases directly on your machine, DDEV provisions everything inside isolated Docker containers, resulting in a clean, reproducible setup.
Before exploring the advantages, it’s helpful to understand what TYPO3 DDEV actually refers to.
What Is TYPO3 DDEV?
TYPO3 DDEV refers to using the TYPO3 CMS together with the DDEV local development tool to create a fast, consistent, and easy-to-manage development environment.
DDEV is a Docker-based local development system that automates the setup of web server, PHP runtime, and database services.
It allows you to spin up fully functional TYPO3 environments in minutes without manually configuring Apache/Nginx, PHP versions, or MySQL. Because the environment is containerized, it behaves the same across different machines and operating systems.
TYPO3 projects benefit from DDEV’s built-in support, making it straightforward to start new projects or onboard team members quickly.
Key Benefits of Installing TYPO3 with DDEV
Installing TYPO3 with DDEV offers practical advantages for developers, teams, and agencies working on local or collaborative projects. It focuses on reliability, speed, and consistency rather than manual setup.
- Consistency: Every team member runs an identical development environment, reducing “works on my machine” issues.
- Automation: Common tasks such as shell access, Composer operations, and database management are integrated into simple DDEV commands.
- Flexibility: Additional services like Redis or Solr can be added with minimal configuration when required.
- Isolation: The TYPO3 environment runs separately from your host system, preventing conflicts with other projects.
- Community Support: DDEV is actively maintained and widely used within the TYPO3 ecosystem, ensuring ongoing compatibility and documentation.
This combination makes DDEV a reliable choice for modern TYPO3 development workflows.
Architecture of DDEV & TYPO3
DDEV uses Docker to create a containerized environment that runs all services required for TYPO3 locally. Instead of installing and configuring a full web stack on your machine, DDEV orchestrates dedicated containers that work together to serve your site.
How it works:
- You execute
ddevcommands on your local machine. - The DDEV CLI manages and coordinates the underlying Docker containers.
- The web container runs the Apache/PHP environment and accesses your project files (typically in the
public/directory). - The database container runs MariaDB, storing TYPO3 content and configuration.
- Your browser accesses the project through a local domain (for example,
https:// my-typo3-project(.)ddev(.)site), which routes traffic to the web container.
This architecture ensures isolation, consistency across machines, and easy reproducibility of development environments.
TYPO3 Versions & Support Roadmap
TYPO3 follows a structured release cycle designed to provide long-term stability for professional projects. Only two versions matter for a new DDEV project in November 2026: TYPO3 v14 LTS and TYPO3 v13.4 LTS.
| TYPO3 version | Status | Latest release | Free support until | Use it for |
| v14 LTS | Stable, recommended | 14.3.10 (22 Oct 2026) | 30 Jun 2029 | New projects |
| v13.4 LTS | Old stable | 13.4.37 (22 Oct 2026) | 31 Dec 2027 | Existing projects |
- LTS (Long-Term Support): free bug and security fixes from the TYPO3 project.
- ELTS (Extended Long-Term Support): a paid extension after free support ends. TYPO3 v12 left free support on 30 April 2026 and is now ELTS only; upgrade such projects to v13 or v14.
Source: get.typo3.org, checked November 2026.
Which PHP version does TYPO3 need in DDEV?
When setting up TYPO3 with DDEV, the PHP version is set per project in .ddev/config.yaml (or with ddev config --php-version), so you never install PHP on your computer.
PHP & TYPO3 Compatibility
| TYPO3 Version | Supported PHP Versions | PHP used in the official DDEV tutorial |
| 14 LTS | 8.2, 8.3, 8.4, 8.5 | 8.4 |
| 13.4 LTS | 8.2, 8.3, 8.4, 8.5 | 8.4 |
Migration note: projects still on TYPO3 v12 or older should be upgraded before you build new features; set the PHP version in DDEV to match the target TYPO3 version.
Sources: get.typo3.org and TYPO3 Getting Started.
Which TYPO3 version should you install?
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 v14 LTS is the preferred option for new projects because it offers modern features, improved performance, and extended support coverage.
Note: TYPO3 v14 requires PHP 8.2 or higher. The official TYPO3 DDEV tutorial uses PHP 8.4 and a Composer-based setup.
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.
Getting Started with TYPO3 DDEV Setup
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
- macOS: OrbStack, Lima, Docker Desktop, Rancher Desktop or Colima
- Windows: WSL2 with Docker CE, Docker Desktop or Rancher Desktop; Linux: Docker CE
- DDEV CLI installed
Install DDEV (If Not Already Installed)
Use the method for your operating system from the official DDEV installation guide:
- macOS (Homebrew):
brew install ddev/ddev/ddev - Linux or macOS (install script):
curl -fsSL https://ddev.com/install.sh | bash - Debian/Ubuntu: add the DDEV apt repository from packages.ddev.com, then
sudo apt-get install -y ddev - Windows: the DDEV Windows installer, or WinGet (
winget install DDEV)
Follow the DDEV installation guide for the full steps of each method. After a first install, run mkcert -install once so your browser trusts the local HTTPS certificates.
Verify Installation
After installing Docker and DDEV, confirm that both tools are available and working:
docker --versionddev --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.
Composer Mode vs Classic Installation
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.
Creating the Installation Directory
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-projectcd my-typo3-project
For a fresh installation, this folder can be empty. DDEV will generate the necessary configuration and environment files during setup.
Configure the Project Using ddev config
Once inside your project directory, run the configuration command:
ddev config
To skip the prompts, pass all values at once, as the official TYPO3 tutorial does:
ddev config --project-type=typo3 --docroot=public --php-version=8.4
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 configurationdocker-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.
Installing TYPO3 via Composer
Once DDEV is configured for your project, start it and install TYPO3 with Composer. ddev composer runs Composer inside the web container, so the PHP version from your DDEV configuration is used. You do not need ddev ssh for this step.
Start the DDEV Environment
ddev start
This command launches the required Docker containers, including:
- Web container
- Database container (MariaDB by default)
- Supporting services such as the router and Mailpit
Create the TYPO3 Project with Composer
For TYPO3 v14 LTS:
ddev composer create-project "typo3/cms-base-distribution:^14"
For TYPO3 v13.4 LTS:
ddev composer create-project "typo3/cms-base-distribution:^13"
The command installs the project into the project root and creates public/ as the web root. Do not add public as a target folder: that would create a second, nested project.
Recommended for v14: the Camino Default Theme
Since TYPO3 14.1 the Core ships a default theme. The TYPO3 docs recommend it for first installs:
ddev composer require typo3/theme-camino
File Ownership & Permissions
DDEV runs commands in the web container with your own user ID, so chown commands are normally not needed. If you see write errors, check that the project is not in a folder your Docker provider cannot mount (Lima and Colima only mount your home directory by default).
After completing these steps, the folder contains composer.json, config, packages, public and vendor. The database is still empty until you run the setup.
How do you finish the TYPO3 setup in DDEV?
TYPO3 v13 and v14 can be set up in two ways: with a console command or with the web-based Install Tool. The console command is the fastest.
Option 1: Console setup (recommended)
ddev typo3 setup --server-type=other --driver=mysqli --host=db --port=3306 --dbname=db --username=db --password=db
Answer the prompts for admin user name, password, e-mail and project name. When asked for a basic site, enter your DDEV URL, for example https://my-typo3-site.ddev.site.
Option 2: Web Installer (1-2-3 Install Tool)
ddev exec touch public/FIRST_INSTALLddev launch /typo3/install.php
DDEV provides these database credentials. Enter them when the installer asks:
- Host:
db - Database name:
db - Username:
db - Password:
db - Port:
3306
Set the Development Context
TYPO3 starts in the Production context. For better error output while developing, add this to .ddev/config.yaml and run ddev restart:
web_environment:- TYPO3_CONTEXT=Development/DDEV
Source: TYPO3 setup on first installation.
Note: If you encounter a 404 error or missing directory message, verify that the docroot in .ddev/config.yaml is public.
TYPO3 verifies required PHP extensions, permissions, and server configuration.
Resolve any reported issues before continuing.
Enter the database credentials (or use the default DDEV values). TYPO3 will use this database to store content and settings.
Choose an existing empty database or allow TYPO3 to create a new one automatically.
Set up the administrator account and initial site configuration. Use a secure password for backend access.
Define the site name and choose whether to install a distribution or start with a blank project.
After completion, TYPO3 redirects you to the backend login screen.
Verify Installation Success
After completing the Installation Wizard, confirm that your TYPO3 instance is functioning correctly. Verifying both backend and frontend access ensures that the environment, database, and configuration are working as expected.
Access the TYPO3 Backend
Open the TYPO3 backend login page in your browser. You can typically access it via:
ddev launch /typo3/
Enter the administrator credentials created during installation. Successful login indicates that TYPO3 core services and authentication are operational.
Check Frontend Site Availability
Visit the main project URL:
ddev launch
With the Camino theme on TYPO3 v14 and a basic site created during setup, you see the demo website. ddev describe lists all project URLs.
The site should load without errors. Depending on your setup, you may see a default page, a blank template, or the installed distribution.
Confirm Admin Login Works
After logging into the backend:
- Verify that the dashboard loads correctly
- Navigate to core modules (Page, List, Settings)
- Confirm that no system warnings or errors appear
- Optionally create a test page or content element to ensure database write operations function properly
Successful interaction confirms that TYPO3, database connectivity, and file permissions are correctly configured.
Connect an AI assistant to your local TYPO3
The free MCP Starter Kit for TYPO3 explains how to install AI Foundation, set guard rails and run ten first jobs: a 15-page guide plus an Excel sheet.
Why does TYPO3 not start in DDEV? Troubleshooting
Most DDEV problems come from a stopped Docker provider, busy ports 80/443 or a wrong docroot. Start with ddev utility diagnose, which checks Docker, network, DNS and HTTPS in one run.
DDEV Containers Not Starting
If ddev start fails:
- Ensure Docker is running
- Check available system resources (RAM/CPU)
- Restart Docker and retry
- Review logs for errors:
ddev logs
Port Conflicts
Conflicts occur when another service uses ports 80 or 443.
Solutions:
- Stop local web servers (Apache, Nginx, IIS)
- Stop other Docker containers
- Run:
ddev poweroff
Then restart your project.
Permission Issues
Symptoms may include file write errors or failed installations.
Possible fixes:
- Keep the project inside your home directory (required by Lima and Colima by default)
- Do not run Composer with sudo on the host; use
ddev composer - Restart the project so DDEV can fix mounts:
ddev restart
Database Connection Errors
If TYPO3 cannot connect to the database:
- Confirm the database container is running
- Use default DDEV credentials if unsure:
- Host:
db - Database:
db - Username:
db - Password:
db
- Host:
- Restart the environment:
ddev restart
TYPO3 Install Tool Not Loading
If the Install Tool does not appear:
- For the web installer, check that
public/FIRST_INSTALLexists and open/typo3/install.php - Verify TYPO3 files were installed in the correct docroot
- Confirm
.ddev/config.yamlpoints to the correct directory (e.g.,public) - Clear browser cache or try another browser
- Restart DDEV:
ddev restart
Blank Page or 500 Error
Internal server errors typically indicate configuration or dependency issues.
Recommended checks:
- Review TYPO3 logs in the project directory
- Check DDEV logs:
ddev logs
- Flush the TYPO3 caches:
ddev typo3 cache:flush -v - Ensure required PHP extensions are available
- Verify file permissions and database connectivity
Addressing these common issues will resolve most problems encountered during a TYPO3 installation with DDEV.
Daily TYPO3 DDEV Workflow
Once installation is complete, you will interact primarily with the DDEV environment to manage your project.
The .ddev Folder
The .ddev/ directory contains configuration files that define your local environment:
config.yaml— Core project configuration (PHP version, docroot, project type)docker-compose.*.yaml— Optional service definitions or overridesdb_snapshots/— Optional database backups
Example configuration:
name: my-typo3-projecttype: typo3docroot: publicphp_version: "8.4"webserver_type: nginx-fpmweb_environment:- TYPO3_CONTEXT=Development/DDEV
Common DDEV Commands
These commands help you control and troubleshoot your local TYPO3 environment:
ddev start— Start project containersddev stop— Stop the current projectddev poweroff— Stop all running DDEV projectsddev ssh— Access the web container shellddev composer [args]— Run Composer inside the containerddev exec [command]— Execute arbitrary commands in the containerddev logs— View container logs for debuggingddev describe— Display project URLs and service detailsddev launch: open the site;ddev launch /typo3/opens the backendddev typo3 [command]: run the TYPO3 console, for exampleddev typo3 cache:flushddev xdebug toggle: switch Xdebug on or offddev snapshot: save the database before risky changes
Understanding these commands will streamline daily development tasks and maintenance.
Adding Extra Services & Extensions
DDEV allows you to enhance your TYPO3 development environment by adding additional services such as caching systems or search engines, as well as installing TYPO3 extensions.
These components run alongside your project inside containers and can be enabled with minimal configuration.
Example: Adding Redis
Redis can be used for caching or session storage to improve performance.
Use the official DDEV add-on instead of writing a Docker Compose file by hand:
ddev add-on get ddev/ddev-redisddev restart
The add-on registry also offers official add-ons such as ddev/ddev-memcached. List what is installed with ddev add-on list --installed (DDEV add-ons).
Installing TYPO3 Extensions
TYPO3 functionality can be extended by installing extensions using Composer or the classic file-based approach.
Composer-based installation (recommended):
From your project folder:
ddev composer require georgringer/news
Our guide on how to install TYPO3 extensions via Composer covers version constraints and updates.
This installs the extension and its dependencies in a modern TYPO3 setup.
Classic installation method:
For legacy projects, extension files can be placed directly in:
public/typo3conf/ext/
Both methods are supported within a DDEV environment.
Using an Existing TYPO3 Project with DDEV
DDEV can also be used to run an existing TYPO3 project locally. Instead of creating a new installation, you configure DDEV around the existing codebase, install dependencies, and import the project database.
Import Existing Codebase
Place your existing TYPO3 project files into a local directory and navigate to it:
cd path/to/your-typo3-project
Ensure the project contains the TYPO3 core files and the correct web root (for example, public/, web/, or another configured directory).
Initialize DDEV in the project folder:
ddev config --project-type=typo3
Follow the prompts to set the project name and document root.
Install Dependencies
For Composer-based projects, install required packages inside the container:
ddev startddev composer install
This restores the TYPO3 core, extensions, and dependencies defined in composer.json.
For non-Composer (legacy) projects, ensure all required files and extensions are present in the project directory.
Import Database
TYPO3 requires the project database to function correctly. Import a database dump into the DDEV environment:
ddev import-db --file=path/to/database.sql.gz
DDEV accepts plain and compressed dumps (.sql, .sql.gz, .sql.zst, .zip and others) (DDEV database management). After import, TYPO3 should recognize the existing site content and configuration.
Adjust Configuration & Docroot
Verify that the document root configured in .ddev/config.yaml matches the project’s web directory (commonly public/).
Also check TYPO3 configuration files (such as database connection settings) if needed. In most cases, DDEV’s database credentials can be used:
- Host:
db - Database:
db - Username:
db - Password:
db
Restart the environment to apply any changes:
ddev restart
Your existing TYPO3 project should now run locally within the DDEV environment.
Best Practices & Tips for TYPO3 DDEV Install
Following proven practices helps maintain a stable, reproducible, and efficient local TYPO3 development environment when using DDEV.
Manage Environment in Git
Commit the .ddev/ directory to your version control system so that all team members share the same environment configuration.
Avoid committing files that contain sensitive data (such as local overrides with credentials).
With the configuration tracked in Git, collaborators can clone the repository and start the project with:
ddev start
This ensures consistent development environments across the team.
Using Xdebug
Xdebug enables step-by-step debugging of PHP code.
Turn Xdebug on from your project folder:
ddev xdebug on
Xdebug stays on until the project is restarted. Turn it off with:
ddev xdebug off
Configure your IDE (such as PhpStorm or VS Code) to listen for debugging connections, on port 9003. You can then set breakpoints and inspect variables during execution.
Database Snapshots
DDEV provides snapshot functionality for backing up and restoring the project database.
Create a snapshot:
ddev snapshot
This generates a compressed archive in .ddev/db_snapshots/.
Restore a snapshot:
ddev snapshot restore [snapshotname]
Snapshots are useful for preserving development states or testing changes safely.
Overriding PHP Configuration
Custom PHP settings can be applied using override files.
Create the file:
.ddev/php/ini-overrides.ini
Add the required configuration values, for example:
memory_limit = 512Mmax_execution_time = 240
Restart DDEV to apply the new settings:
ddev restart
This approach allows fine-tuning of the runtime environment without modifying global system settings.
Performance Tips for Local Development
Optimizing your local environment can significantly improve TYPO3 performance when running inside DDEV. Proper configuration reduces page load times, speeds up builds, and ensures smoother development workflows.
Xdebug Performance Considerations
Xdebug is essential for debugging but can noticeably slow down PHP execution when enabled.
Recommendations:
- Enable Xdebug only when actively debugging
- Disable it during normal development to improve performance
- Switch Xdebug without editing files:
ddev xdebug toggle
Check the current state with ddev xdebug status.
Disabling Xdebug when not needed can dramatically speed up TYPO3 backend and frontend responses.
Memory & Execution Settings
Large TYPO3 projects or extension installations may require higher PHP resource limits.
You can adjust settings using a PHP override file:
.ddev/php/ini-overrides.ini
Example configuration:
memory_limit = 512Mmax_execution_time = 240upload_max_filesize = 64Mpost_max_size = 64M
Restart DDEV after changes:
ddev restart
Adequate memory and execution limits help prevent timeouts and installation failures.
Optimizing Docker Performance
Docker resource allocation directly affects TYPO3 performance.
Consider the following optimizations:
- Allocate sufficient RAM and CPU to Docker in its settings
- Use SSD storage for project files and Docker data
- Close unnecessary containers or applications consuming resources
- Restart Docker periodically to clear resource bottlenecks
- On macOS and traditional Windows, keep Mutagen file sync on: DDEV enables it by default there for fast file access
Proper Docker tuning ensures faster container startup times and smoother TYPO3 operation during development.
TYPO3 DDEV Remote Hosting Integration
While DDEV is primarily designed for local development, it can also integrate with remote hosting environments and automated deployment workflows.
This makes it useful for synchronizing data, testing changes, and maintaining consistency between local and remote setups.
Key capabilities include:
- Pulling from Remote Environments:
You can import databases and files from staging or production environments into your local setup using provider-specific integrations.
ddev pull
- Pushing to Remote Environments:
In supported setups, local database or file changes can be pushed back to a remote environment for testing or deployment.
ddev push
- CI/CD Integration:
DDEV can be used in automated pipelines running inside temporary (ephemeral) Docker environments. This enables reproducible builds, automated testing, and consistent deployment processes across teams.
By bridging local development with staging or production systems, DDEV helps maintain alignment between environments while reducing configuration drift.
How do you use AI coding assistants with a DDEV TYPO3 project?
An AI assistant or coding agent works best when it runs the same DDEV commands as you do and reads the official docs. Give it the DDEV and TYPO3 documentation as Markdown and let it call commands through ddev instead of a local PHP.
- Docs for the agent: DDEV publishes its documentation for AI assistants as llms.txt (with links to a Markdown version of every page) and llms-full.txt (all pages in one file). TYPO3 documentation pages offer a "View as Markdown" link.
- Same commands for humans and agents: let the agent use
ddev composer,ddev typo3andddev exec, so PHP and database versions match the project. - Scriptable URLs:
ddev launch --print-urlprints the site URL instead of opening a browser, which helps in terminals, containers and CI. - Safe experiments: take a
ddev snapshotbefore an agent changes the database, and restore it withddev snapshot restore.
If you connect an AI assistant to the TYPO3 backend itself, test it first in the local DDEV site. Our article MCP in practice for TYPO3 shows how this works with real tasks.
Conclusion
DDEV provides a reliable and reproducible environment for local TYPO3 development. The AI Foundation for TYPO3, along with connected providers, prompts, and permissions, should also be tested locally or in a staging environment first.
With a few commands, you can spin up a fully functional TYPO3 environment, share consistent configurations across your team, debug efficiently, and accelerate development workflows.
Its containerized approach ensures reliability, reproducibility, and flexibility, making it a practical choice for modern TYPO3 projects of any size. Installing and using DDEV is straightforward, allowing developers to focus on building and testing rather than managing infrastructure.
Further reading: Installing TYPO3 with DDEV (TYPO3 docs), DDEV CMS quickstarts and DDEV command reference. When the base install runs, pick a design from our TYPO3 templates and add it with Composer.
Free TYPO3 guides with Excel templates
Download free TYPO3 guides on upgrades, the EU AI Act, accessibility and MCP, each as a PDF with an Excel sheet.
FAQs For TYPO3 DDEV
Yes. Docker is required because DDEV uses containers to run the web server, PHP runtime, and database. Without Docker running, DDEV cannot start the TYPO3 environment.
Use the latest Long-Term Support (LTS) version of TYPO3. LTS releases provide extended security updates, stability, and compatibility with modern PHP versions, making them ideal for new projects.
DDEV automatically provisions a database with standard credentials:
- Host:
db - Database:
db - Username:
db - Password:
db
These values typically work out of the box during the TYPO3 Installation Wizard.
Yes. You can configure DDEV in the existing project directory, install dependencies (if Composer is used), and import the project database. Once configured, the site will run locally inside the DDEV environment.
Performance issues are usually caused by insufficient system resources, Xdebug being enabled, or low Docker memory allocation. Disabling Xdebug when not debugging and increasing Docker resources typically improves speed.
Open your project URL followed by /typo3, for example:
https:// my-typo3-project(.)ddev(.)site / typo3
Log in using the administrator credentials created during the Installation Wizard.
Need help with your setup?
Stuck on your local TYPO3 environment? Send a TYPO3 support inquiry.
Wolfgang Weber
Brand & Communication LeadWolfgang Weber shapes TYPO3 with passion and expertise. As a TYPO3 enthusiast at T3Planet Shop, he has contributed to TYPO3 projects that make websites faster and more secure. Outside of TYPO3, you’ll probably find him exploring local cafés and enjoying football.
More From Author