---
title: "TYPO3 extension management with Composer"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:extensions-composer@main"
source: "Administration/ExtensionManagement/Composer/Index.rst"
rendered: "2026-09-26T10:15:30+00:00"
---

# TYPO3 extension management with Composer {#extensions-composer}

> [!NOTE]
> **See also**
>
> For a beginner-friendly introduction on extension management with Composer,
> see:
>
> -   [Getting Started Guide: Working with extensions](https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/Extensions/Index.html#extensions_index)

**Table of contents**

-   [Install or require an extension with Composer](https://docs.typo3.org/permalink/t3coreapi:install-or-require-an-extension-with-composer@main)
-   [Installing a custom extension or site package via Composer](https://docs.typo3.org/permalink/t3coreapi:installing-a-custom-extension-or-site-package-via-composer@main)
-   [Installing extensions from a different source](https://docs.typo3.org/permalink/t3coreapi:installing-extensions-from-a-different-source@main)
-   [Extension update via Composer](https://docs.typo3.org/permalink/t3coreapi:extension-update-via-composer@main)
-   [Removing an extension via Composer](https://docs.typo3.org/permalink/t3coreapi:removing-an-extension-via-composer@main)

## Install or require an extension with Composer {#extensions-composer-installation}

Composer distinguishes between **requiring** and **installing** an
extension. By default you can require any package registered on
[https://packagist.org/](https://packagist.org/) and compatible with your current requirements.

### Composer require {#extensions-composer-require}

When you use the command `composer require` or its abbreviated, shortened version
`composer req` the requirement will be added to the file `composer.json` and Composer
installs the latest version that satisfies the version constraints in
`composer.json`, and then writes the resolved version to `composer.lock`.

For example, to install the extension [`georgringer/news`](https://packagist.org/packages/georgringer/news):

```bash
# Install the news extension
composer require georgringer/news
```

If necessary you can also require the extension by adding a version requirement:

**typo3_root$**

```bash
# Install the news extension in version 12.3.0 or any minor level above
composer require georgringer/news:"^12.3"

# Install the news extension from the main branch
composer require georgringer/news:"dev-main"
```

> [!NOTE]
> **See also**
>
> -   [command "composer require"](https://getcomposer.org/doc/03-cli.md#require-r)
> -   ["Writing Version Constraints" in the Composer documentation](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints)
>     for more version constraint examples.

Composer will then download the extension into the `vendor` folder and
execute any additional installation steps.

You can now commit the files `composer.json` and `composer.lock`
to [Git](https://docs.typo3.org/permalink/t3coreapi:version-control@main).

### Composer install {#extensions-composer-install}

If the same project is installed on other systems — such as a co-worker’s
computer or the production server (if you are working with
[Git and Composer deployment](https://docs.typo3.org/permalink/t3coreapi:deployment-git-composer@main)) —
you do not need to run `composer require` again. Instead, use
`composer install` to install the exact versions defined in
`composer.lock`:

**typo3_root$**

```bash
git update

# Install versions that have been changed
composer install

# Rerun the setup for all extensions
vendor/bin/typo3 extension:setup
```

> [!NOTE]
> **See also**
>
> -   [command "composer install"](https://getcomposer.org/doc/03-cli.md#install-i)

### List extensions {#extensions-composer-list}

Just like in the TYPO3 core, extensions are individual Composer packages.
You can list all installed packages, including extensions, using the following command:

```bash
composer info
```

This will display a list of all installed packages along with their names and version numbers.

> [!NOTE]
> **See also**
>
> -   [command "composer info"](https://getcomposer.org/doc/03-cli.md#show-info)

### Extension setup {#extensions-composer-extension-setup}

Many extensions make TYPO3-specific changes to your system that Composer cannot
detect. For example, an extension might define its own
database tables in the TCA or require static data to be imported.

You can run the following command to set up specific or all extensions:

**typo3_root$**

```bash
# Setup the extension with key "news"
vendor/bin/typo3 extension:setup --extension=news

# Setup all extensions
vendor/bin/typo3 extension:setup
```

You can also [Automate extension setup](https://docs.typo3.org/permalink/t3coreapi:extensions-composer-extension-setup@main).

> [!TIP]
> The Composer package name (for example, `georgringer/news`) and the TYPO3
> extension key (for example `news`) are **not the same**.
>
> The **extension key** is defined in the extension’s `composer.json`
> under the key
> [extra.typo3/cms.extension-key](https://docs.typo3.org/permalink/t3coreapi:ext-composer-json-property-extension-key@main).

### Automate extension setup {#extensions-composer-extension-setup-automate}

You can run the [extension setup command](https://docs.typo3.org/permalink/t3coreapi:extensions-composer-extension-setup@main)
automatically after each require / install / update command by adding it to
the `script` section of your project's `composer.json`:

**composer.json (Excerpt)**

```json
{
  "scripts":{
    "typo3-cms-scripts": [
      "vendor/bin/typo3 extension:setup"
    ],
    "post-autoload-dump": [
      "@typo3-cms-scripts"
    ]
  }
}

```

> [!NOTE]
> **See also**
>
> -   [Composer scripts](https://getcomposer.org/doc/articles/scripts.md)

## Installing a custom extension or site package via Composer {#extensions-composer-installation-custom}

In most projects there will be one special extension per site, called a site
package, that contains the theme and configuration for that site.

There could also be custom extensions only for a specific domain in that
project.

Both these types of extensions should be placed in the `packages` folder
and required in Composer as local (`@dev`) versions. This will create a symlink from
`packages` to `vendor`, allowing the extensions to be used
like any other package.

1.  Place the extension into the folder `packages` so that its `composer.json`
    can be found at [`packages/ext_key/composer.json`](../../../ExtensionArchitecture/FileStructure/ComposerJson.md#file-extension-composer-json)
1.  Require the extension using Composer and specifying the `@dev` version:

    **typo3_root$**

    ```bash
    # Require a custom site package
    composer require myvendor/my-site-package:"@dev"

    # Require a custom extension
    composer require myvendor/my-local-extension:"@dev"
    ```

Composer install will work as described in
[Composer install](https://docs.typo3.org/permalink/t3coreapi:extensions-composer-install@main) if the extension is
available on the system where you run the `composer install` command.

You will usually commit the
files `composer.json`, `composer.lock` and the content of the
`packages` folder to the same Git repository.

> [!NOTE]
> **See also**
>
> -   ["Creating a site package", Getting started tutorial](https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/FirstProject/CreateSitePackage.html#creating-a-site-package)
> -   ["Site package installation", Site Package Tutorial](https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/MinimalExample/Index.html#extension-installation)
> -   [Extension development](https://docs.typo3.org/permalink/t3coreapi:extension-development@main)

## Installing extensions from a different source {#extensions-composer-installation-source}

You can define [Composer repositories](https://getcomposer.org/doc/05-repositories.md)
to install packages (including TYPO3 extensions) from different sources like
[Git](https://getcomposer.org/doc/05-repositories.md#vcs), a [local path](https://getcomposer.org/doc/05-repositories.md#path) and
[Private Packagist](https://getcomposer.org/doc/05-repositories.md#private-packagist).

After adding the repository to your project's `composer.json`, you can
require the extension using the standard `composer require` command.

**composer.json (Excerpt)**

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url":  "git@bitbucket.org:vendor/my-private-repo.git"
    },
    {
      "type": "artifact",
      "url": "path/to/directory/with/zips/"
    },
    {
      "type": "path",
      "url": "../../local_packages/my_custom_extension/"
    },
    {
      "type": "path",
      "url": "site_packages/*"
    }
  ]
}

```

## Extension update via Composer {#extensions-composer-update}

> [!WARNING]
> **Attention**
>
> The command `composer update` cannot easily be reverted. We recommend
> using [Version control (Git)](https://docs.typo3.org/permalink/t3coreapi:version-control@main)
> and committing both files `composer.json` and `composer.lock` before
> running an update command.
>
> If you are not using Git, make a backup of these two files before the update.

The following command updates all installed Composer packages (both TYPO3
extensions and other PHP packages/libraries) to the newest version that the
current constraints in your `composer.json` allow. It will write the
new versions to file `composer.lock`:

```bash
# Warning: Make a backup of composer.json and composer.lock before proceeding!
composer update
```

If you want to do a major Upgrade, for example from [`georgringer/news`](https://packagist.org/packages/georgringer/news)
Version 11.x to 12.x, you can require that extension with a different version number:

```bash
# Attention make a backup of the composer.json and composer.lock first!!
composer require georgringer/news:"^12"
```

> [!NOTE]
> **See also**
>
> -   [command "composer update"](https://getcomposer.org/doc/03-cli.md#update-u-upgrade)
> -   [command "composer require"](https://getcomposer.org/doc/03-cli.md#require-r)
> -   ["Writing Version Constraints" in the Composer documentation](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints)

### Downgrading an extension {#extensions-composer-downgrade}

If an extension does not work after upgrade you can downgrade the extension
by requiring a specific version:

```bash
# Attention make a backup of the composer.json and composer.lock first!!
composer require georgringer/news:"12.0.42"
```

The extension will remain locked to the specified version and will not be
updated until you change the version constraint using the `composer require`
command.

### Reverting extension updates {#extensions-composer-update-revert}

As a last resort you can revert any changes you have made by restoring the files
`composer.json` and `composer.lock` and running the command
`composer install`:

**typo3_root$**

```bash
# restore composer.json and composer.lock
git stash

# Reinstall previously used versions
composer install
```

> [!NOTE]
> **See also**
>
> -   [command "composer install"](https://getcomposer.org/doc/03-cli.md#install-i)

## Removing an extension via Composer {#extensions-composer-remove}

You can remove an extension requirement from your project's
`composer.json` by using the command `composer remove`, but bear in mind that the
extension will only be uninstalled if it is no longer required by any
of the installed packages.

```bash
# Check the extension is not in use first!
# composer remove georgringer/news
```

Composer will not check if the extension is currently in use. Composer can only
check if the extension is listed in the `require` section of the
`composer.json` file of another extension.

> [!NOTE]
> **See also**
>
> -   [command "composer remove"](https://getcomposer.org/doc/03-cli.md#remove-rm-uninstall)

### Check if the extension is in use {#extensions-composer-remove-used}

Manually verify whether the extension is still in use before uninstalling it.

-   Does the extension have [Site sets](https://docs.typo3.org/permalink/t3coreapi:site-sets@main)
    that are required by a site configuration or another extension's site set?
-   Are you using any plugins or content elements provided by the extension?
    Tip: Extension [`fixpunkt/backendtools`](https://packagist.org/packages/fixpunkt/backendtools) lists all plugins and
    content elements that are in use.
-   Have you included any TypoScript provided by the extension? Or tables
    defined by its TCA? Does it include [Middleware](https://docs.typo3.org/permalink/t3coreapi:request-handling@main),
    [Console commands (CLI)](https://docs.typo3.org/permalink/t3coreapi:symfony-console-commands@main)
    or any other functionality that your project relies on?

### Why an extension cannot be uninstalled {#extensions-composer-remove-why}

If Composer refuses to remove an extension with `composer remove` you can
run the following command to find out what other packages require the Extension
you want to remove:

```bash
# Show which package requires the extension
composer why georgringer/news
```

> [!NOTE]
> **See also**
>
> -   [command "composer why"](https://getcomposer.org/doc/03-cli.md#depends-why)

In very stubborn cases the following tricks can help:

Ensure you have a backup of the files `composer.json` and
`composer.lock` or have committed them to Git.

Then delete the `vendor` folder (it will be restored by Composer), delete
`composer.lock` and run `composer install`. This will reinstall
your requirements from your `composer.json`. Deleting the Composer cache
first might also help.

**typo3_root$**

```bash
composer clear-cache
rm -rf vendor/
rm composer.lock
composer install
```

> [!NOTE]
> **See also**
>
> -   [command "composer install"](https://getcomposer.org/doc/03-cli.md#install-i)
> -   [command "composer clear-cache"](https://getcomposer.org/doc/03-cli.md#clear-cache-clearcache-cc)