Update Contao 3 auf Contao 4
- 3.5
- 4.4
- 4.9
- 4.13
Wichtige Hinweise
- Lies dir einmal den kompletten Beitrag von Anfang bis Ende durch und starte erst dann mit der Umsetzung!
- Erstelle auf JEDEN FALL ein komplettes Backup der Datenbank und Dateien.
1. Contao 3 für das Update vorbereiten
Du hast noch eine Installation mit Contao 2?
Dann kannst du nicht direkt auf Contao 4 aktualisieren. Du solltest zunächst ein Update auf die letzte Version von Contao 2 durchführen. Das ist die Version Contao 2.11.17. Danach führst du ein Update auf Contao 3.5.40 aus und erst danach kannst du auf Contao 4 aktualisieren. Das wichtigste sind dabei immer die Datenbankupdates. Layout- und Templateanpassungen musst du erst durchführen, nachdem du auf Contao 4 aktualisiert hast.
1.1. Contao 3 auf den aktuellen Stand bringen
Für ein Upgrade von Contao 3 auf Contao 4 muss deine Contao 3 Installation aktuell sein. Du musst deshalb ein Update deiner Installation auf die letzte Version von Contao 3.5 (3.5.40) durchführen. Da der Support für Contao 3.5 komplett eingestellt wurde, kannst du das Update aktuell nur noch manuell per FTP bzw. direkt auf der Konsole durchführen.
1.2. Alte Dateistruktur vorhanden?
Solltest du eine alte Installation haben, die bereits von Contao 2 auf Contao 3 aktualisiert worden ist, dann prüfe vorher, ob du schon auf die files-Ordnerstruktur migriert hast.
In Contao 2 wurden die Uploads standardmäßig unter /tl_files abgelegt. Seit Contao 3 werden die Benutzerdateien unter /files abgelegt. Contao 3 konnte jedoch noch mit dem Pfad /tl_files umgehen. Seit Contao 4 funktioniert das nicht mehr. Kontrolliere deshalb vor dem Update von Contao 3 auf Contao 4 deine Ordnerstruktur. Sind deine eigenen Dateien noch unter /tl_files abgelegt, dann muss das umgestellt werden.
Wie du hier vorgehst, erfährst du in folgendem Beitrag:
Unter Contao 3 den Ordner tl_files nach files umstellen
2. Erweiterungen unter Contao 3.5 prüfen
Im Laufe der Jahre haben sich in einigen Installationen viele Erweiterungen angesammelt. Die Liste mit den installierten Erweiterungen findest du in der Erweiterungsverwaltung bzw. in der Paketverwaltung.
Contao 3 Extension-Repository Ende Mai 2022 abgeschaltet
Der Erweiterungskatalog wurde abgeschaltet und kann nicht mehr aufgerufen werden. Es ist somit auch kein Update der Erweiterungen mehr direkt in Contao 3 möglich.
Um dennoch die Erweiterungsverwaltung im Backend aufzurufen, lösche die komplette URL unter Einstellungen > Erweiterungsverwaltung > Extension Repository-URL.
Denke bitte auch daran, dass sich in einer Installation manuell installierte Erweiterungen befinden können, die nicht in der Erweiterungsverwaltung bzw. in der Paketverwaltung zu sehen sind. Dazu musst du dir den Inhalt des Ordners /system/modules per FTP oder anderen Tools ansehen.
Prüfe, welche Erweiterungen tatsächlich im Einsatz sind. Nicht genutzte Erweiterungen löschst du am besten noch vor dem Update auf Contao 4. Im Anschluss immer daran denken, dass du das Installtool aufrufst, um die Datenbank zu aktualisieren.
3. Sind die Erweiterungen für Contao 4 freigegeben?
Leider sind nicht alle Erweiterungen von Contao 3.5 auch unter Contao 4 verfügbar. Deswegen prüfst du als Nächstes, ob deine genutzten Erweiterungen (Abhängkeiten kannst du igonrieren) für Contao 4 verfügbar sind. (https://extensions.contao.org).
Es kann auch vorkommen, dass eine Erweiterung unter einem anderen, neuen Namen verfügbar ist. Zum Beispiel lautet die Erweiterung [calendar_extended] unter Contao 4 [kmielke/calendar-extended-bundle]. Um die Installation aller nötigen Abhängigkeiten kümmert sich der Contao Manager bzw. der Composer automatisch.
Falls deine verwendete Erweiterung nicht für Contao 4 verfügbar ist, dann musst du eine entsprechende Alternative suchen.
4. Backup von Contao 3.5 erstellen
Nachdem Contao 3 jetzt für das Update auf Contao 4 vorbereitet ist, sicherst du folgende Dateien und Ordner:
- /files
- /templates
- /system/config/localconfig.php
- /system/config/langconfig.php
- /system/config/dcaconfig.php
Außerdem solltest du alle Erweiterungen sichern, die manuell installiert wurden
(/system/modules/deine_manuell_installierte_erweiterung).
Als Letztes muss noch die Datenbank gesichert werden. Um zu vermeiden, dass die gesicherte Datenbank unnötig groß ist, solltest du zuvor im Backend die Systemwartung aufrufen und die Daten bereinigen. Alternativ können beim Datenbank-Export auch folgende Tabellen ausgeschlossen werden:
- tl_lock
- tl_log
- tl_search
- tl_search_index
- tl_session
- tl_undo
- tl_version
Diese Tabellen enthalten keine Informationen, die für Update oder Wiederherstellung einer Installation benötigt werden. Die Tabellen werden beim Aufruf des Installtools neu erstellt.
Als Beispiel hier der Exportdialog von phpMyAdmin für angepasste Tabellen.

5. Contao 4 installieren und Datenbank aktualisieren
5.1. Datenbank
Für Contao 4 benötigst du eine eigene Datenbank. Lege diese an und importiere die in Schritt 4 exportierten SQL-Daten von Contao 3.5.
5.2. Eigene Subdomain oder Lokale Umgebung
Für die Installation von Contao 4 konfigurierst du dir am besten eine neue Subdomain. D. h. deine Website unter Contao 3.5 läuft während es kompletten Vorgangs parallel weiter. Denk bitte daran, dass der Document-Root der Subdomain zwingend auf den Ordner /public zeigen muss.
Statt der Subdomain-Variante kannst du das ganze Upgrade auch lokal per XMAPP oder MAMP durchführen und später auf den Live-Server übertragen.
5.3. Installation von Contao 4 durchführen
Als Nächstes installierst du Contao 4 über den Contao Manager (alternativ über die Kommandozeile per Composer).
Bei der Installation über den Manager wird dir die Auswahl zwischen der aktuellsten Version von Contao (derzeit Contao 5.1) und der LTS-Version (derzeit Contao 4.13) angeboten. Bitte wähle hier Contao 4.13 aus. Solltest du auf Contao 5 aktualisieren möchten, dann musst du trotzdem den Zwischenschritt über Contao 4 machen, da sonst nicht alle Änderungen in der Datenbank enthalten sind.
Tipp
Weitere Details zur Installation von Contao 4 findest du in folgender Anleitung:
Contao 4 installieren per Contao Manager.
5.4. Installtool aufrufen
Nach erfolgreicher Installation verbindest du Contao 4 mit der neuen Datenbank, in der sich die importierten Daten von Contao 3.5 befinden (siehe 5.1.).
Wenn du alles richtig gemacht hast, dann werden dir jetzt vom Installtool bzw. der Contao Datenbankmigration zahlreiche Tabellen und Felder zum Anlegen, Aktualisieren und Löschen angeboten.
Außerdem werden automatisch die entsprechenden Migrations durchgeführt. (siehe Screenshot)

WICHTIG: Keine Löschungen
Du führst zunächst KEINE Löschungen (DROP-Anweisungen) durch, sondern nur die SQL-Anweisungen unter «Tabellen anlegen (create)», «Tabellen ändern (alter)», und «Spalten ändern (alter)». Das ist wichtig, da derzeit noch keine Erweiterungen installiert sind und daher die Tabellen und Daten der Erweiterungen gelöscht würden.

6. Kompatible Erweiterungen installieren
Jetzt installierst du alle kompatiblen Erweiterungen über den Contao Manager (alternativ über die Kommandozeile) und führst danach das Installtool aus. Auch jetzt werden noch keine Löschungen vorgenommen.
Die Erweiterungen, die als Ersatz für nicht kompatible Erweiterungen vorgesehen sind, solltest du ebenfalls installieren.
7. Alte Daten übertragen
7.1. Dateien übertragen
In diesem Schritt arbeiten wir überwiegend direkt im Filesystem deiner Installation.
Übertrage jetzt folgende gesicherte Ordner per FTP/SFTP in deine neue Installation
- /files
- /templates
Dateien öffentlich erreichbar machen
Im Ordner unter /files müssen jetzt noch auf öffentlich gestellt werden, damit die Ressourcen auch im Web angezeigt werden können. Dazu meldest du dich im Backend an und navigierst zur Dateiverwaltung. Bitte beachte dabei, dass alle Dateien in Unterordnern von /files liegen müssen. Dateien, die direkt im Ordner /files liegen, können nicht öffentlich verfügbar gemacht werden.
Zur Sicherheit solltest du jetzt einmal unter Systemwartung > Symlinks neu erstellen ausführen.

7.2. Einstellungen übertragen
Danach solltest du die gesicherte localconfig.php anschauen und alle Einstellungen, die weiterhin benötigt werden, manuell übertragen. Dazu gehören unter anderem die Einstellungen für das Datumsformat, Systemadmin oder die Uploadgröße.
In Contao 4 werden die Einstellungen für die verwendete Datenbank nicht mehr in der localconfig.php gespeichert. Diese Eintragungen werden also nicht in die neue localconfig.php übernommen. Auch einige Einträge, die von Erweiterungen stammen, die du nun nicht mehr verwendest, werden nicht in die neue localconfig.php übernommen. Die localconfig.php findest du in Contao 4 wie bisher im Ordner /system/config/.
Wenn du dir unsicher bist, welche Einstellungen du übernehmen solltest, kannst du die Einstellungen auch im Backend von Contao 4 neu setzen.
7.3. Anpassungen dcaconfig und langconfig
Wenn du keine Anpassungen an diesen beiden Dateien vorgenommen hast, dann kannst du diesen Schritt überspringen.
Die Eintragungen aus der dcaconfig.php und langconfig.php könnten zwar noch unter /system/config verwendet werden, das ist allerdings veraltet. Verwende deshalb den "neuen Weg". Dazu legst du einen neuen Ordner /contao an und darin die Unterordner dca und languages.
Unter /contao/dca benötigst du für jede Tabellenanpassung eine eigene Datei. In diese übernehmen wir die Einstellungen aus der dcaconfig.php.
Unter /contao/languages gibt es für jede Sprache einen Ordner. In diesen Ordner werden die Dateien für die Sprachkonfiguration abgelegt. Für die deutsche Sprache ist das dann der Ordner /de. Hier würde z. B. die Anpassung für den More-Link in der Datei default.php erfolgen.
Auf weitere Details gehen wir hier nicht ein, da das den Rahmen sprengen würde. Weitere Infos findest du hier:
Migration und Anpassung der Konfigurationsdateien dcaconfig und langconfig.
7.4. Anwendungs-Cache leeren

Damit die neue Konfiguration in Contao aktiv wird, musst du jetzt per Contao Manager den Anwendungs-Cache neu aufbauen. (Systemwartung > Prod.-Cache erneuern)
8. Manuell zu installierende Erweiterungen
Wichtiger Hinweis
Bitte übertrage die Erweiterungen nur manuell, wenn es keine andere Möglichkeit gibt. Der bevorzugte Weg ist immer die Installation über den Contao Manager.
Viele Erweiterungen, die in Contao 3 verwendet wurden, funktionieren prinzipiell auch mit Contao 4. Es lohnt es sich also mit jeder einzelnen Erweiterung einen Versuch zu starten, die du nicht über den Contao Manager (alternativ über die Kommandozeile) installieren konntest bzw. für die du keinen adäquaten Ersatz gefunden hast.
Dazu kopierst du die gesicherten Ordner deine_manuell_installierte_erweiterung oder deine_nicht_verfuegbare_erweiterung in den Ordner /system/modules, rufst das Installtool auf (keine Löschungen vornehmen) und leerst danach den Prod.-Cache über den Contao Manager.
Dieses Verfahren kommt allerdings an seine Grenzen, wenn die oben genannten Erweiterungen Abhängigkeiten haben. Diese Abhängigkeiten müssten auch installiert werden, dabei kann es aber zu Unverträglichkeiten mit über den Contao Manager oder Composer installierten Erweiterungen kommen.
Ich empfehle dir jede manuelle Installation einzeln durchzuführen und jeweils Front- und Backend auf Fehlerfreiheit zu überprüfen. Somit bemerkst du gleich, welche der Erweiterungen Probleme bereitet.
9. Weitere Nacharbeiten unter Contao 4
Wenn Contao 4 fehlerfrei funktioniert kommen je nach Umfang der Installation noch zahlreiche weitere Arbeiten auf dich zu. Dazu gehören unter anderem:
- Systemeinstellungen prüfen
- Layouteinstellungen prüfen
- CSS-Anpassungen durchführen
- Templates prüfen und anpassen
- Formulare prüfen
- SMTP-Versand einrichten
- relevante Einträge aus der alten .htaccess übernehmen (nicht 1:1 kopieren!)
- Berechtigungen prüfen und anpassen
- URL-Suffix konfigurieren
- Caching neu einstellen
- Installtool aufrufen und die verbliebenen Löschungen durchführen (vorher Backup!)
- …
10. Website Live schalten
Da wir das Upgrade auf einer Subdomain (siehe Schritt 5) durchgeführt haben, läuft auf unserer Hauptdomain immer noch das alte Contao 3.5. Das wollen wir nun ändern.
Wir schalten nun unserer Contao 4 Version live. Dazu ändern wir den Document-Root der Hauptdomain auf den Ordner /web der Contao 4 Installation.
Ich empfehle dir die alte Contao 3 Installation noch für eine Weile über eine Subdomain erreichbar zu halten. Das erleichtert die nachträgliche Fehlersuche bei Problemen, die du in deiner neuen Contao 4 Installation vielleicht zunächst übersehen hast.
Viel Spaß beim Update von Contao 3 auf Contao 4.
Empfehlung Videokurs
Eine ausführliche Schritt für Schritt Anleitung findest du im Videokurs
"Umstieg auf Contao 4".
Über den Autor

Christian Feneberg ist der Gründer der Contao-Academy und erstellt seit 2010 Websites mit Contao. Außerdem ist er im Team von trakked.io. und regelmäßig auf YouTube in der Contao Show zu sehen. Neben Contao begeistert er sich für Online-Marketing, Unternehmertum und Persönlichkeitsentwicklung.
6 Kommentare
Maik |
Hallo und danke für die Anleitung! Ich kann mich irren, aber meinst Du nicht, dass ein Hinweis auf tl_files für die, die von Contao 2 auf 3 migriert haben und noch nicht auf Files umgestellt haben, Sinn machen könnte? Contao 3 kann ja noch problemlos mit dem tl_files Ordner fahren. Sollte man vielleicht im Zuge der Vorbereitung unter Punkt 1 einfügen. Sonst geht das wohl in die Contao Hose. :-)
Ladina Gisep |
Dankeschön, Christian
Sehr hilfreiche Doku!
Sehr gerne!
Manuel von Heugel |
Tolle Anleitung, vielen Dank!
Gert W. |
Hallo, unter Punkt 5.2. wird, wie bisher bekannt, vom Rootverzeichnis /web geschrieben. Im Handbuch wird aber auch vom Ordner /public geschrieben:
https://docs.contao.org/manual/de/installation/systemvoraussetzungen/#hosting-konfiguration
Wie ist der aktuelle Stand, wenn man eine 4.13 installieren will? Wie soll die Ordnerstruktur aussehen? Vielen Dank im Voraus.
Hallo Gert, ab Contao 4.13 kannst du beides verwenden. Ich empfehle allerdings bereits den Ordner /public zu verwenden, da es ab Contao 5 kein /web mehr gibt.
Micha |
Vielen Dank für diese hilfreiche Anleitung.
Im Kapitel 5.4 steht:
"nur die SQL-Anweisungen unter "Tabellen anlegen" und "Spalten ändern""
ich nehme an "Tabellen ändern" sollte hier auch mit durchgeführt werden (habe ich jedenfalls beim Upgrade so gemacht) - nur eben nicht "Tabellen löschen" und "Spalten löschen".
Hallo Micha, danke für den Hinweis. Ich werde das im Text entsprechend anpassen.
Daniela |
Ich weiß ich bin spät dran...
Ich habe heute den ganzen Tag versucht, von 3.5 auf 4.13 zu kommen, aber der Import der zuvor gesicherten SQL Datenbank ist schier unmöglich. Kaum sind die Daten drin, meckert der Contao Manager, Unknown database type enum requested, Doctrine\DBAL\Platforms\MySQL80Platform may not support it. Ich hab keine Ahnung, was ich anders machen soll.
Ohne den Import funktioniert alles, aber das ist ja nicht der Sinn der Sache. Meine alte Seite war ziemlich aufwändig, ich wäre wirklich dankbar für eine Hinweis.
Ich vermute, es gibt in deiner Datenbank ein oder mehrere Felder, die den Typ "enum" haben. Nach meiner Recherche (siehe hier) wird das allerdings nicht mehr von Doctrine unterstützt. D. h. du müsstest die entsprechenden Spalten vom Typ Enums und TinyInts suchen und dann umwandeln oder entfernen.
Dazu müsstest du zunächst prüfen, welche Erweiterung diese Spalten angelegen haben. Evtl. benötigst du diese Erweiterung unter Contao 4 nicht mehr.
Mehr Support kann ich dir über diesen Weg nicht anbieten. Wenn du damit nicht zum Ziel kommst, bitte einmal im Contao-Forum dein Problem posten. Alternativ kannst du dich auch an unseren Support wenden und wir versuchen dir im Rahmen eines bezahlten Support-Auftrags zu helfen.
Einen Kommentar schreiben