I've been through enough TYPO3 migrations to know that the difference between a smooth transition and a six-month nightmare comes down to preparation. TYPO3 is a powerful CMS — it's been around since 1998 and runs some seriously complex enterprise sites, especially in the DACH region. But when it's time to migrate, whether you're upgrading between major TYPO3 versions or moving to an entirely different platform, the process can get ugly fast if you don't have a plan.

This is the checklist I wish someone had handed me before my first TYPO3 migration. It's not theoretical. Every item here exists because I've seen what happens when you skip it.

Table of Contents

TYPO3 Migration Checklist: A Developer's Step-by-Step Guide

Assess Your Current TYPO3 Installation

Before you touch anything, you need to understand exactly what you're working with. This sounds obvious. It isn't. I've walked into projects where the team didn't even know which TYPO3 version they were running in production.

Version and Environment Audit

Start here:

# Check your TYPO3 version
php typo3/sysext/core/bin/typo3 --version

# Or check via the backend: Help > About TYPO3

Document the following:

  • TYPO3 version (major and minor — e.g., TYPO3 v11.5.38 LTS)
  • PHP version running on the server
  • Database type and version (MySQL, MariaDB, PostgreSQL)
  • Web server (Apache, Nginx)
  • Composer-based or classic installation — this matters enormously
  • Number of sites/domains in the installation (multi-site setups add complexity)
  • Total number of pages and content elements in the page tree

User and Permission Mapping

TYPO3's backend user and group permission system is notoriously granular. Export your be_users and be_groups tables and document:

  • How many backend users exist
  • What custom permissions are configured
  • Which users have admin access
  • Any custom TSconfig overrides

If you're migrating to a different CMS, you'll need to map these roles to the new system's permission model. If you're upgrading TYPO3 versions, some permission configurations may need updating.

TypoScript and Configuration Complexity

Run a quick audit of your TypoScript setup:

# Count your TypoScript files
find . -name '*.typoscript' -o -name '*.ts' | wc -l

# Check for setup.txt and constants.txt (legacy format)
find . -name 'setup.txt' -o -name 'constants.txt' | wc -l

If you've got hundreds of TypoScript files with deeply nested configurations, expect the migration to take longer. I've seen TYPO3 installations with 10,000+ lines of TypoScript that had evolved over 15 years. That's not a weekend project.

Define Your Migration Strategy

There are fundamentally three types of TYPO3 migrations, and you need to decide which one you're doing before anything else.

Migration Type When to Choose Complexity Typical Timeline
TYPO3 version upgrade (e.g., v10 → v12) You want to stay on TYPO3 Medium-High 4-12 weeks
TYPO3 to headless CMS (e.g., Contentful, Strapi, Sanity) You want modern frontend flexibility High 8-20 weeks
TYPO3 to another traditional CMS (e.g., WordPress, Drupal) You want a different monolithic CMS Medium 6-16 weeks
TYPO3 to headless TYPO3 (using EXT:headless) You want TYPO3 backend with modern frontend Medium 6-14 weeks

Upgrading Within TYPO3

If you're staying on TYPO3, the official upgrade path requires stepping through each LTS version. You can't jump from v8 to v12 directly. Well, you can try. Don't.

The recommended path as of 2025:

  • v8 LTS → v9 LTS → v10 LTS → v11 LTS → v12 LTS → v13 LTS

TYPO3 v13 LTS was released in late 2024 and is the current long-term support version. TYPO3 v12 LTS will receive security updates until April 2026 through the Extended Long Term Support (ELTS) program.

Migrating Away From TYPO3

If you're moving to a headless architecture — and honestly, for many teams this makes a lot of sense — you'll want to evaluate your frontend framework options. We've done extensive work with Next.js and Astro as frontend layers paired with headless CMS platforms.

The key question is: does your content model justify the complexity of TYPO3? If you're running a marketing site with 200 pages, TYPO3 is probably overkill. If you're running a multi-language enterprise portal with complex workflows, the content modeling work during migration is going to be significant regardless of where you're going.

Content Audit and Data Mapping

This is where migrations live or die. Content.

Database Export and Analysis

TYPO3 stores content primarily in these tables:

  • pages — the page tree structure
  • tt_content — content elements
  • sys_file and sys_file_reference — media assets (FAL)
  • sys_category — categories
  • tx_news_domain_model_news — if you're using the news extension

Export your content and get real numbers:

-- Count pages by type
SELECT doktype, COUNT(*) as count 
FROM pages 
WHERE deleted = 0 
GROUP BY doktype;

-- Count content elements by type
SELECT CType, COUNT(*) as count 
FROM tt_content 
WHERE deleted = 0 AND hidden = 0 
GROUP BY CType 
ORDER BY count DESC;

-- Count file references
SELECT COUNT(*) FROM sys_file WHERE missing = 0;

Content Type Mapping

Create a spreadsheet mapping every TYPO3 content type (CType) to its equivalent in the target system. Common TYPO3 content types you'll encounter:

  • text, textmedia, textpic — standard text content
  • image — image galleries
  • table — data tables
  • bullets — lists
  • uploads — file lists
  • html — raw HTML (these are always fun during migration)
  • list — plugin content (this is where it gets complicated)
  • Custom content types from extensions

The list CType is the tricky one. It represents plugin content — news listings, forms, custom functionality — and each one needs individual attention.

Multi-Language Content

TYPO3 handles translations through connected mode (where translations are linked to a default language record) or free mode. Check which approach your site uses:

-- Check translation setup
SELECT sys_language_uid, COUNT(*) 
FROM pages 
WHERE deleted = 0 
GROUP BY sys_language_uid;

If you've got 8 languages with connected mode translations, your migration data mapping just got 8x more complex. Plan accordingly.

TYPO3 Migration Checklist: A Developer's Step-by-Step Guide - architecture

Technical Infrastructure Preparation

Server Requirements

If you're upgrading to TYPO3 v13, here are the minimum requirements as of 2025:

  • PHP 8.2 or higher (8.3 recommended)
  • MySQL 8.0+ or MariaDB 10.4+ or PostgreSQL 12+
  • 256MB PHP memory limit minimum (512MB recommended)
  • Composer 2.7+

Staging Environment

Never — and I cannot stress this enough — never run a migration directly on production. Set up:

  1. A staging environment that mirrors production
  2. A separate database copy
  3. Identical PHP and server configurations
  4. File storage access (or a copy of fileadmin)
# Clone your database to staging
mysqldump -u root -p production_db | mysql -u root -p staging_db

# Rsync fileadmin
rsync -avz production:/var/www/html/fileadmin/ staging:/var/www/html/fileadmin/

Backup Strategy

Before any migration work begins:

  • Full database dump with timestamps
  • Complete file system backup including fileadmin, typo3conf, and any custom extension directories
  • Document your LocalConfiguration.php and AdditionalConfiguration.php settings
  • Export your TypoScript templates

Store these backups somewhere completely separate from the migration environment. I keep at least three copies.

Extension and Integration Inventory

TYPO3 extensions are probably the biggest source of migration headaches. Here's how to handle them.

List All Installed Extensions

# Composer-based installation
composer show | grep typo3

# Or check the PackageStates.php
cat typo3conf/PackageStates.php

Categorize Each Extension

For every extension, determine:

Category Action Required Example
Core system extension Usually handled by upgrade wizard fluid_styled_content, form
Maintained TER extension Check compatibility with target version news, powermail, solr
Abandoned TER extension Find replacement or custom solution Various
Custom site extension Needs manual migration/rewrite Your site_package
Commercial extension Contact vendor for migration path in2publish, various

Common Extension Migration Paths

Some extensions I see in almost every TYPO3 migration:

  • EXT:news (Georg Ringer) — Check version compatibility; v11+ works with TYPO3 v12/v13
  • EXT:powermail — Popular form extension; alternatives include EXT:form (core)
  • EXT:realurl — Deprecated since TYPO3 v9; replaced by core routing
  • EXT:tt_address — Usually straightforward upgrade
  • EXT:gridelements or EXT:flux — These layout extensions cause the most pain during upgrades. If you're migrating away from TYPO3, expect significant work extracting content from grid structures.

SEO Preservation Plan

Skipping this section has cost companies millions in organic traffic. Don't be that team.

URL Mapping

  1. Crawl your entire current site with Screaming Frog, Sitebulb, or Ahrefs
  2. Export all URLs (expect thousands for large TYPO3 sites)
  3. Create a complete 1:1 URL mapping document
  4. Identify your top 100 pages by organic traffic (check Google Search Console)
  5. Prioritize redirect accuracy for high-traffic pages

Redirect Implementation

# Example .htaccess redirects
RedirectPermanent /old-typo3-path/page.html /new-path/page
RedirectPermanent /index.php?id=123 /about-us

For large-scale redirects, use a redirect management solution rather than cramming thousands of rules into .htaccess. If you're moving to a modern stack, most frameworks and hosting platforms (Vercel, Netlify) have redirect configuration files.

Meta Data Migration

TYPO3 stores SEO metadata in the pages table (since EXT:seo became a core extension in v9):

  • seo_title
  • og_title, og_description, og_image
  • twitter_title, twitter_description, twitter_image
  • canonical_link
  • no_index, no_follow

Make sure you export and map all of this. Losing your meta descriptions across 500 pages is a preventable disaster.

The Migration Execution Phase

For TYPO3 Version Upgrades

Follow this sequence for each version step:

  1. Update Composer dependencies to the next LTS version
  2. Run the Upgrade Wizard in the Install Tool (Admin Tools > Upgrade)
  3. Execute database analyzer to update schema
  4. Check deprecation log for issues
  5. Update extensions to compatible versions
  6. Fix TypoScript deprecations and breaking changes
  7. Test thoroughly before moving to the next version step
# Update TYPO3 core via Composer
composer require typo3/cms-core:^13.4 typo3/cms-backend:^13.4 \
  typo3/cms-frontend:^13.4 --with-all-dependencies

# Run upgrade wizards via CLI
php typo3/sysext/core/bin/typo3 upgrade:run

# Database schema update
php typo3/sysext/core/bin/typo3 database:updateschema

For Platform Migrations

If you're migrating to a headless CMS architecture, the execution phase looks different:

  1. Set up the new CMS and configure content models
  2. Build migration scripts to transform TYPO3 data
  3. Migrate content in batches — start with the simplest content types
  4. Handle media assets — download from fileadmin and upload to new asset storage
  5. Build the frontend with your chosen framework
  6. Implement redirects before go-live
  7. DNS cutover and monitoring

For the actual data transformation, I typically write Python or Node.js scripts that read from the TYPO3 database and push content to the new CMS via API:

import mysql.connector
import requests

# Connect to TYPO3 database
db = mysql.connector.connect(
    host="localhost",
    user="typo3",
    password="password",
    database="typo3_db"
)

cursor = db.cursor(dictionary=True)
cursor.execute("""
    SELECT uid, title, description, slug, 
           seo_title, og_description 
    FROM pages 
    WHERE deleted = 0 AND hidden = 0 
    AND sys_language_uid = 0
    ORDER BY sorting
""")

for page in cursor.fetchall():
    # Transform and push to new CMS
    payload = {
        "title": page["title"],
        "slug": page["slug"],
        "seoTitle": page["seo_title"] or page["title"],
        "description": page["og_description"] or page["description"]
    }
    # POST to your new CMS API
    response = requests.post(
        "https://api.new-cms.com/content",
        json=payload,
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    )
    print(f"Migrated page {page['uid']}: {response.status_code}")

Testing and Quality Assurance

Automated Testing Checklist

  • All pages return 200 status codes
  • No broken internal links
  • All images load correctly
  • Forms submit successfully
  • Search functionality works
  • Multi-language switching works
  • Redirects from old URLs work correctly
  • Canonical URLs are correct
  • XML sitemaps are valid and accessible
  • robots.txt is properly configured
  • SSL certificates are valid
  • Page load times are acceptable (under 3 seconds)

Visual Regression Testing

Use tools like Percy, BackstopJS, or Playwright for visual comparison:

# BackstopJS example
npx backstop init
# Configure scenarios in backstop.json
npx backstop reference  # Capture current site
npx backstop test       # Compare after migration

Performance Benchmarks

Measure before and after. Your migration should ideally improve performance, not degrade it.

Metric Pre-Migration Target Post-Migration Target
TTFB < 800ms < 200ms
LCP < 2.5s < 1.5s
CLS < 0.1 < 0.05
FID/INP < 200ms < 100ms
PageSpeed Score 50-70 90+

If you're moving from server-rendered TYPO3 to a static or edge-rendered frontend, you should see dramatic improvements in these numbers.

Post-Migration Monitoring

The migration isn't done when you flip the DNS. Monitor these for at least 30 days:

  1. Google Search Console — Watch for crawl errors, coverage issues, and indexing problems. Expect some fluctuation in the first two weeks.
  2. Analytics — Compare traffic patterns week-over-week with pre-migration baselines.
  3. 404 errors — Set up logging for 404s and add redirects for any URLs you missed.
  4. Core Web Vitals — Monitor real-user data via CrUX or your analytics platform.
  5. Server logs — Watch for unusual error patterns.

Set up alerts for traffic drops exceeding 20% on any page that was previously in your top 50.

Common TYPO3 Migration Pitfalls

These are mistakes I've seen (and sometimes made) across dozens of migrations:

1. Ignoring soft-deleted records. TYPO3 uses deleted=1 flags rather than actually removing records. Your migration scripts need to filter these out, or you'll import thousands of records that were deleted years ago.

2. Forgetting about workspaces. If the site uses TYPO3 workspaces for editorial workflows, you might have draft content mixed into your export. Always filter for t3ver_wsid = 0 to get only live content.

3. Underestimating RTE content. TYPO3's rich text editor output can contain custom tags, <link> tags with TYPO3-specific syntax, and t3:// URIs. You need to parse and convert all of these.

4. Breaking file references. TYPO3's File Abstraction Layer (FAL) uses sys_file_reference to connect files to content. It's not a simple "image field on the content record" — it's a relation table. Your migration scripts need to follow these references.

5. Not testing with real content volumes. Your migration script works great with 10 test pages. It fails catastrophically with 15,000 pages and 50,000 content elements. Always test at scale.

If you're planning a migration and want to avoid these pitfalls, we've guided several enterprise teams through TYPO3 migrations — feel free to reach out and we can talk through your specific situation.

FAQ

How long does a TYPO3 migration typically take? It depends heavily on the complexity of your installation. A straightforward TYPO3 v11 to v13 upgrade for a single-language site with standard extensions might take 4-6 weeks. A full platform migration of a multi-language enterprise TYPO3 site with custom extensions can easily take 3-6 months. The content audit phase alone can take 2-4 weeks for large sites.

Can I skip TYPO3 LTS versions during an upgrade? Technically, you shouldn't. The official recommendation is to upgrade through each LTS version sequentially (v8 → v9 → v10 → v11 → v12 → v13) because each version includes upgrade wizards that handle data migrations for that specific step. Skipping versions means those data migrations don't run, and you'll end up with corrupted or orphaned data. Some agencies claim they can do skip-version upgrades, but I've seen it cause subtle data issues that surface months later.

Should I migrate from TYPO3 to WordPress? It depends on your needs. WordPress handles simple marketing sites well, but if you chose TYPO3 originally because of complex multi-language requirements, granular permissions, or enterprise workflows, WordPress might be a step backward. Consider whether a headless CMS paired with a modern frontend framework might be a better fit. We've written about headless CMS development approaches that often make more sense for teams leaving enterprise CMS platforms.

What happens to my SEO rankings during a TYPO3 migration? Expect some ranking fluctuation for 2-6 weeks, even with perfect redirects. Google needs time to recrawl and reindex your content. To minimize impact: implement 301 redirects for every URL, keep your content structure as close to the original as possible, submit updated sitemaps immediately, and use the Change of Address tool in Google Search Console if you're changing domains. Sites that handle redirects properly typically recover within 4-8 weeks.

How do I handle TYPO3 extensions that don't exist on the target platform? First, determine what the extension actually does. Many TYPO3 extensions provide functionality that's built into modern platforms (like form builders, SEO tools, or redirect management). For custom functionality, you'll need to either find an equivalent plugin/service or build custom features. Create a spreadsheet listing each extension, its purpose, and the replacement strategy.

Is it worth moving to headless TYPO3 instead of migrating away entirely? The TYPO3 headless extension (EXT:headless) is a legitimate option if your team is comfortable with TYPO3's backend but wants a modern frontend. It exposes TYPO3 content as JSON APIs, letting you build your frontend with Next.js, Nuxt, or Astro. This approach preserves your existing content structure and editorial workflows while modernizing the presentation layer. It's a good middle ground, though it does mean you're still maintaining a TYPO3 backend.

What's the cost of a TYPO3 migration in 2025? Ballpark figures: a TYPO3 version upgrade for a mid-sized site runs $15,000-$50,000. A full platform migration to a headless architecture ranges from $40,000-$150,000+ depending on content volume, number of languages, custom functionality, and integration complexity. These aren't small numbers, but compare them against the cost of maintaining an outdated, insecure CMS installation. You can check our pricing page for more details on how we structure these projects.

Do I need to rebuild my templates from scratch? For TYPO3 version upgrades, usually not entirely — but you will need to update Fluid templates to handle deprecated ViewHelpers and new APIs. For platform migrations, yes, you're building a new frontend. The good news is that modern frameworks like Next.js and Astro make it significantly faster to build performant frontends than it was in the Fluid/TypoScript era. Your design can stay the same; the implementation just changes.