How to Install TYPO3 with Composer: Step-by-Step Guide

Why Install TYPO3 with Composer?

Installing TYPO3 with Composer is the preferred approach for professional projects because it simplifies dependency management, improves deployment consistency and makes TYPO3 Core and extension updates easier to control.

With a traditional TYPO3 Installation, teams must download the Core package, upload files manually, install extensions separately and check compatibility each time something changes. This becomes difficult when multiple extensions depend on different TYPO3, PHP or library versions.

Common problems include:

• Finding extensions compatible with the installed TYPO3 Version
• Checking PHP and package requirements manually
• Managing conflicting dependencies
• Reproducing the same setup across local, staging and production environments
• Updating TYPO3 Core and several extensions without breaking the project

Composer solves these problems by reading the dependencies defined in composer.json, selecting compatible package versions and recording the exact installation in composer.lock.

Key Benefits of Using Composer with TYPO3

Using Composer allows TYPO3 teams to:

• Install TYPO3 Core and extensions through the command line
• Resolve package dependencies automatically
• Maintain consistent development, staging and production environments
• Track dependency changes through Git
• Update or remove extensions more safely
• Roll back package changes using composer.lock
• Integrate security checks, testing and CI/CD workflows
• Create faster and more reliable deployment processes

In simple terms, Composer replaces manual package management with a repeatable and controlled workflow. This makes it especially valuable for TYPO3 agencies, development teams and organizations managing long-term or business-critical websites.

Which TYPO3 Version Should You Install?

For a new TYPO3 project, install TYPO3 v14 LTS. It is the current stable release and the version officially recommended for new projects. TYPO3 v13 LTS remains supported for existing websites that are not yet ready to upgrade, while TYPO3 v12 now requires Extended Long Term Support for continued security and compliance updates.

TYPO3 v14 and v13 System Requirements

Both TYPO3 v14 and v13 support:

• PHP 8.2, 8.3, 8.4 and 8.5
• MariaDB 10.4.3 or later
• MySQL 8.0.17 or later
• PostgreSQL 10 or later
• SQLite 3.8.3 or later

Before installation, confirm that your PHP CLI version, web-server PHP version and database meet the requirements of the selected TYPO3 release.

Important: Commands written for TYPO3 7.6, TYPO3 8.1, PHP 5.3, dev-master or typo3/cms:^7.6 are obsolete. They should not be used for a modern TYPO3 Composer installation.

What Do You Need Before Installing TYPO3?

Before installing TYPO3 with Composer, confirm that your server or local development environment meets the technical requirements. Most installation problems come from incompatible PHP versions, missing extensions, incorrect permissions or a web server pointing to the wrong directory.

TYPO3 Composer Installation Requirements

Make sure your environment includes:

• Linux, macOS or Windows
• Command-line or SSH access
• Composer 2.x
• A PHP version supported by your TYPO3 release
• Required PHP extensions
• A supported MySQL, MariaDB, PostgreSQL or SQLite database
• Valid database credentials
• Permission to create directories and symbolic links
• Access to change the website’s document root
• An empty project directory

Check PHP and Composer

Run these commands before creating the TYPO3 project:

which php
which composer

On Windows, use:

where php
where composer

The command-line PHP version and the web-server PHP version should both meet the requirements of the selected TYPO3 release.

Confirm the Web Root

Your hosting environment must allow the domain or virtual host to point to the TYPO3 project’s public/ directory. This keeps configuration, dependencies and application files outside the publicly accessible web root.

Pre-installation check: Do not begin the TYPO3 Composer installation until PHP, Composer, database access, directory permissions and the public/ document root are confirmed.

How Do You Install Composer?

Before installing Composer, check whether it is already available on your local machine or server:

composer --version

If the command returns a Composer 2.x version, you can move directly to the TYPO3 installation.

Important: composer install does not install Composer itself. It installs the dependencies defined in an existing project’s composer.json or composer.lock file.

Install Composer Globally

A global Composer installation allows you to run Composer from any project directory:

composer install

On Windows, the simplest method is to use the official Composer installer, which configures Composer and adds it to the system PATH. On Linux and macOS, follow Composer’s current command-line installation instructions. Avoid copying installer signatures from old tutorials because the verification hash changes when a new installer is released.

Use Composer Locally

When Composer is stored inside the current directory as composer.phar, run commands through PHP:

php composer.phar install

The global and local methods perform the same Composer tasks. Only the command prefix changes.

After installation, verify that Composer is working correctly:

composer --version
composer diagnose

If the server has multiple PHP versions, confirm which PHP and Composer executables are active:

which php
which composer

On Windows, use:

where php
where composer

Some managed hosting environments require full executable paths, such as:

/path/to/php /path/to/composer create-project \
  "typo3/cms-base-distribution:^14" my-typo3-project

Composer is PHP’s dependency manager. Packagist is the default public repository from which Composer discovers many packages. They are connected services, but they are not the same tool.

How to Install TYPO3 v14 with Composer

Installing TYPO3 v14 with Composer involves four main steps: creating the project, configuring the public document root, completing TYPO3 setup and verifying the installation.

Step 1: Create the TYPO3 Project

Run the following command from the parent directory in which the new project folder should be created:

composer create-project \
 "typo3/cms-base-distribution:^14" \
 my-typo3-project

Enter the new project directory:

cd my-typo3-project

The destination directory must be empty. Hidden files created by an IDE, Git initialization or operating system can prevent composer create-project from running successfully.

Composer downloads TYPO3 Core, required system packages and their compatible dependencies. It also creates the initial project structure, including composer.json, composer.lock, public/, packages/, config/, var/ and vendor/.

To create a TYPO3 v13 LTS project instead, change the version constraint:

composer create-project \
 "typo3/cms-base-distribution:^13" \
 my-typo3-project

Step 2: Point the Web Server to public/

Configure the Apache, Nginx, IIS or hosting document root to point to:

/path/to/my-typo3-project/public

Older TYPO3 Composer projects may use a directory named web but the current Base Distribution uses public/.

This structure prevents configuration files, dependencies and application code from being directly accessible through the browser. Only files intended for public web access should be exposed through public/.

Step 3: Complete the TYPO3 Installation

The recommended command-line method is:

./vendor/bin/typo3 setup

The guided setup asks for:

• Database connection details
• Administrator username and password
• Project or site name
• Initial site configuration

Alternatively, start the browser-based installation wizard by creating an empty FIRST_INSTALL file:

touch public/FIRST_INSTALL

On Windows PowerShell, use:

New-Item public/FIRST_INSTALL -ItemType File

Then open the project URL in a browser. TYPO3 checks the PHP environment, file permissions, database connection and required extensions before completing the installation.

Step 4: Verify the TYPO3 Installation

After setup, confirm that:

• The frontend opens without an installation error
• The backend is available at /typo3/
• The administrator account works
• The domain points to the public/ directory
• composer.json and composer.loc exist
• The environment scan reports no critical issues
• The database connection works
• Project files are stored in version control
• composer.lock is committed to Git

A successful Composer-based installation gives the project a repeatable foundation. The same locked package versions can then be installed across development, staging and production environments using:

composer install

How to Install TYPO3 with DDEV

DDEV is one of the simplest ways to install TYPO3 locally. It creates a consistent Docker-based environment containing the web server, PHP and database, so developers do not need to configure each service manually.

DDEV is designed for local TYPO3 development only. Production websites should be deployed using a separate hosting and deployment workflow.

Prerequisites

Before starting, install:

• Docker
• DDEV
• Git
• A terminal or command-line application

Composer does not need to be installed separately on the host machine because DDEV can run Composer inside its web container.

Step 1: Create the Project Directory

Create an empty folder and move into it:

mkdir my-typo3-project
cd my-typo3-project

Step 2: Configure DDEV for TYPO3

Configure the project as a TYPO3 installation with public/ as its document root:

ddev config \
 --project-type=typo3 \
 --docroot=public \
 --php-version=8.4

The configuration is stored in .ddev/config.yaml, allowing every developer to start the same local environment.

Start the containers:

ddev start

Step 3: Install TYPO3 v14 with Composer

Create the TYPO3 v14 project inside the current directory:

ddev composer create-project “typo3/cms-base-distribution:^14”

DDEV runs Composer inside the container and installs TYPO3 Core, required packages and the standard project structure.

Step 4: Add the Optional Camino Theme

For a ready-to-view demonstration website, install the Camino theme:

ddev composer require typo3/theme-camino

Camino is optional. It provides a quick frontend starting point and can later be replaced with a custom TYPO3 site package.

Step 5: Complete the TYPO3 Setup

Run the TYPO3 setup command using DDEV’s database credentials:

ddev typo3 setup \
 --server-type=other \
 --driver=mysqli \
 --host=db \
 --port=3306 \
 --dbname=db \
 --username=db \
 --password=db \
 --admin-username=admin \
 --admin-user-password="Replace-With-A-Strong-Password" \
 --admin-email=admin@example.com \
 --project-name="My TYPO3 Website" \
 --force

Replace the sample administrator password and email address before running the command. DDEV automatically provides the database named db with the username and password db for local development.

The setup command creates the database connection, administrator account and basic TYPO3 configuration.

Step 6: Open the TYPO3 Website

Launch the Camino demonstration page:

ddev launch /camino

Open the TYPO3 Backend:

ddev launch /typo3/

Sign in using the administrator credentials created during setup.

Verify the DDEV Installation

Check that:

• DDEV starts without container errors
• TYPO3 opens in the browser
• The backend login works
• The document root is set to public/
• composer.json and composer.loc exist
• The database connection works

View the project URL, database details and container status with:

ddev describe

To stop the local environment without deleting the project, run:

ddev stop

Start it again later with:

ddev start

Existing TYPO3 project: When working from an existing Git repository, run ddev composer install instead of ddev composer create-project. This installs the exact package versions recorded in the project’s composer.lock file.

Understanding the TYPO3 Composer Project Structure

A Composer-based TYPO3 project separates public files, configuration, custom packages and third-party dependencies.

Commit composer.json and composer.lock to Git. Do not commit vendor/, because Composer can recreate it with:

composer install

Composer, Packagist and TER: What Is the Difference?

• Composer: Installs, updates and removes PHP packages.
• Packagist: Composer’s default public package repository.
• TER: TYPO3’s extension catalogue for discovering extensions and checking compatibility.
• composer.typo3.org: An additional repository mainly used for certain legacy packages.

Most modern TYPO3 Extensions are installed through Packagist. Add composer.typo3.org only when an extension’s documentation specifically requires it.

How to Install a TYPO3 Extension with Composer

First, find the extension in the TYPO3 Extension Repository, Packagist or its official documentation and confirm its Composer package name.

Composer package names use this format:

vendor/package-name

For example:

Extension key: extension_builder
Composer package: friendsoftypo3/extension-builder

Install the Extension

To install the TYPO3 News extension, run the following command from the project root:

composer require georgringer/news

Composer will:

• Add the package to composer.json
• Select a version compatible with the project
• Install its dependencies
• Update composer.lock

TYPO3’s official documentation recommends using the extension’s Composer package name with composer require.

Complete the Extension Setup

After installation, run:

./vendor/bin/typo3 extension:setup

This completes TYPO3-specific setup tasks, including database schema changes and package configuration.

To install a specific major version, use an appropriate constraint:

composer require georgringer/news:"^14"

For most projects, the unversioned command is safer because Composer selects the latest release compatible with the installed TYPO3 version. The current News package supports modern TYPO3 installations.

Avoid using * as a version constraint because it permits an uncontrolled range of releases.

Install a Standard PHP Package

Composer can also install ordinary PHP libraries:

composer require monolog/monolog

Composer makes the package available through the project’s standard autoloader in vendor/autoload.php.

Remove an Extension

To remove the News extension, run:

composer remove georgringer/news
./vendor/bin/typo3 extension:setup

After installing, updating or removing an extension, commit the updated composer.json and composer.lock files so the same dependency versions can be reproduced across development, staging and production.

What Is the Difference Between require, install and update?

Composer commands serve different purposes: