How to Upgrade a TYPO3 v12 Site to v13 LTS

Why v12 sites need a plan now

TYPO3 12 reached the end of free community support on 30 April 2026 and moved into paid ELTS coverage. If your site still runs on that branch, security fixes now arrive only through an ELTS subscription, and the pool of compatible extension releases shrinks as maintainers target newer cores.

TYPO3 13 LTS, currently maintained as the 13.4 release line, is the version the TYPO3 project recommends for existing projects. Free support runs until 31 December 2027, with ELTS coverage available until 2030. New projects typically start on TYPO3 14 LTS, the current stable, but a v12 site does not have to make that larger jump in one step. Moving to v13 first keeps the amount of breaking change manageable, and the same upgrade workflow applies later when you continue to v14.

Whichever target you choose, treat the upgrade as a planned project rather than a button click. The official installation documentation splits major upgrades into pre-upgrade tasks, the core update itself, and post-upgrade tasks, and that structure is worth following literally.

Start with an inventory

Before touching any file, record what the site actually consists of:

• the exact core version and whether the installation is Composer-based or classic mode;
• PHP version and database type and version;
• every installed extension with its version number and vendor;
• the site package and any custom TypoScript, Fluid templates or TCA overrides;
• integrations such as single sign-on, ERPs, search services or newsletter tools;
• scheduled tasks and anything else that depends on backend behavior.

The installation mode matters more than most teams expect. Composer-based and classic installations follow different upgrade procedures in the official documentation, so write it down now instead of discovering the difference halfway through.

Check the environment first

According to the release information on get.typo3.org, TYPO3 13 runs on PHP 8.2 through 8.5, with MariaDB 10.4.3+, MySQL 8.0.17+, PostgreSQL 10.0+ or SQLite 3.8.3+ as supported databases.

Verify that your hosting can actually supply a supported PHP version before you schedule anything. If the site currently runs on an older PHP release, settle the PHP move as its own change first where practical, so the core upgrade does not mix two variables into one failure mode.

Audit extensions and the site package

The core upgrade itself is usually the easy part. Most real work sits in third-party code.

For each extension in the inventory, check whether the maintainer ships a release compatible with v13, and record the answer in a simple matrix: compatible, needs an update, needs a replacement, or can be dropped entirely. Extensions that have not seen a release in years are candidates for removal before the upgrade, not after.

Custom code needs the same treatment. The backend Upgrade module includes an extension scanner that checks extension code against the breaking changes of the target version. Run it early, on a copy, and treat its output as your worklist. Each major version removes deprecated APIs, and the core changelog documents every removal in detail, so a scan plus the changelog gives you a realistic estimate of the development effort involved.

If the site relies on a customized site package, review its TypoScript and templates specifically. Overrides built years ago can keep rendering while quietly depending on markup or ViewHelper behavior that no longer exists in v13.

Back up, then rehearse on staging

Take a full backup: database, file system and composer.lock. Then prove the backup works by restoring it somewhere. A backup that has never been restored is a hope, not a rollback plan.

Build a staging environment that mirrors production as closely as possible, including PHP version and database type, and run the entire upgrade there first. Define acceptance tests before you start, covering more than the home page:

• backend login and the most common editor workflows;
• frontend rendering of the main page types and of older, complex content;
• forms, search and any payment or member flows;
• redirects, languages and SEO-relevant metadata;
• scheduled tasks, integrations and email delivery.

We use the same structure in our Joomla upgrade planning guide because the discipline transfers between platforms: the point of staging is to find every problem while it is still free to fix.

Run the upgrade

The exact steps depend on your installation mode, but a Composer-based upgrade follows this pattern:

1. On staging, change the TYPO3 core constraint in composer.json to the v13 LTS line, for example "typo3/cms-core": "^13.4".
2. Update extension constraints at the same time so composer update resolves every package to a v13-compatible release.
3. Log into the backend and open the Upgrade module. Work through the upgrade wizards and apply the database changes the tool proposes.
4. On servers where the backend is inconvenient to use, the wizards can also be run from the command line, for example vendor/bin/typo3 upgrade:run for all pending wizards.

Do not run the wizards and the code cleanup simultaneously. Apply the database and configuration migrations first, confirm the backend behaves, then start fixing what the scanner flagged.

Sites installed in classic mode follow a different procedure documented in the same chapter of the official documentation. If you are still on classic mode and the site is expected to live for years, this upgrade is a reasonable moment to plan the migration to Composer, because it is the workflow the core documentation now treats as primary.

Post-upgrade tasks

After the wizards finish, the site is upgraded but not yet verified:

• clear the system caches and regenerate anything that was cached across versions;
• check the system log and deprecation log for entries that appeared during the switch;
• run the full acceptance test list from staging against the upgraded copy;
• compare frontend rendering on real content pages, not just the home page;
• confirm scheduled tasks, redirect rules and external integrations still work.

Fix what the tests find, then repeat the sequence on production inside a maintenance window you have announced in advance. Keep the rollback plan warm until acceptance tests pass there too: know who can trigger it, how long a restore takes, and what to do with data created during the window if the site accepts orders or form submissions.

What usually goes wrong

Patterns that repeatedly show up in v13 upgrade projects are worth knowing before you start:

• Extensions without a v13 release. Either the maintainer stopped maintaining the package, or the compatible release exists but nobody raised the constraint in composer.json. The scanner cannot tell these apart, so check the extension’s release history manually before you plan around it.
• Site package TypoScript that silently broke. Templates keep rendering, but conditions or data processing that used deprecated syntax now produce empty output somewhere deep in the page. This is why frontend comparison should happen on representative old content, not only on freshly created test pages.
• PHP version mismatches on shared hosting. The host offers PHP 8.2 on paper, but the CLI and the web server run different versions, and the upgrade behaves differently depending on which one executed it. Check both before the maintenance window.
• Skipped wizards on large databases. A wizard that times out halfway through leaves migration markers in an inconsistent state. On big sites, run the wizards from the command line instead of the browser so a PHP max_execution_time limit does not interrupt the work.

None of these are arguments against the upgrade. They are arguments for the staging rehearsal and the acceptance test list, which exist precisely to catch this class of problem while it is still cheap.

Close the loop

After the production upgrade, update your inventory so it reflects v13, remove extensions you flagged as droppable, and note the PHP and database versions actually in use. Record what the scanner flagged and how long the work took. The next major upgrade, whenever it comes, will be shorter to plan if this one ended with accurate notes.

If the audit turns up more custom code than your team can absorb in the available window, that is the point where external help pays for itself. Our TYPO3 development service handles upgrades, extension compatibility work and site package migrations, and the TYPO3 platform page describes what we maintain on that stack in general.