Dem Theme fehlt das Stylesheet style.css: warum WordPress ein Theme-ZIP ablehnt

Welche Fehlermeldung zeigt WordPress?

Beim Hochladen eines Themes als ZIP im WordPress-Backend bricht die Installation mit einer von zwei Meldungen ab. Auf einer deutschen Installation:

Das Theme wird von der hochgeladenen Datei theme.zip installiert
Entpacken des Pakets …
Das Theme wird installiert …
Das Paket konnte nicht installiert werden. Dem Theme fehlt das Stylesheet style.css.
Die Theme-Installation ist fehlgeschlagen.

Auf einer englischen Installation:

Installing theme from uploaded file: theme.zip
Unpacking the package…
Installing the theme…
The package could not be installed. The theme is missing the style.css stylesheet.
Theme installation failed.

Die zweite Meldung betrifft eine style.css ohne brauchbaren Kopf:

Das Paket konnte nicht installiert werden. Das Stylesheet style.css enthält keinen gültigen Theme-Header.
The package could not be installed. The style.css stylesheet does not contain a valid theme header.

Warum fehlt sie, wenn sie doch im ZIP liegt?

Die Meldung klingt, als gäbe es gar keine style.css. Geprüft wird aber die Stelle, nicht das Vorhandensein im Archiv: Eine Ebene zu tief wird genauso gemeldet wie fehlend.

Eine neue style.css ändert nichts: Die Datei war da, nur nicht dort, wo WordPress sie liest. Bei der zweiten Meldung stimmt die Struktur, und es geht um den Kopfkommentar.

Was prüft WordPress beim Entpacken?

  1. Entpacken. Einen Eintrag __MACOSX/ an der Wurzel entpackt WordPress nicht (file.php).
  2. Welcher Ordner ist das Theme? Besteht die oberste Ebene des entpackten Archivs aus genau einem Eintrag und ist das ein Ordner, gilt dessen Inhalt als Theme. Bei mehreren Einträgen oder einer einzelnen Datei gilt die Archivwurzel selbst als Theme, der Ordnername kommt dann aus dem ZIP-Dateinamen.
  3. Gibt es style.css? Sie muss in genau diesem Ordner liegen, sonst kommt die erste Meldung.
  4. Gibt es einen Kopf? WordPress liest nur die ersten 8 KB der Datei und sucht eine Zeile, die (nach beliebig vielen Leerzeichen, Tabs und den Zeichen / * # @) mit Theme Name: beginnt, ohne Beachtung der Groß- und Kleinschreibung. Fehlt die Zeile oder steht dahinter kein Wert, kommt die zweite Meldung.
  5. Danach verlangt WordPress eine index.php, templates/index.html oder block-templates/index.html, sofern kein Template:-Kopf (Child-Theme) vorliegt. Fehlt sie, folgt auf den allgemeinen Satz ein Detailtext, der mit „Template is missing.“ beginnt (in der deutschen PO-Datei 7.1.3 nicht gefunden, also vermutlich englisch).

Was heißt das für typische Archive?

  • theme-main/theme/style.css: Geprüft wird theme-main/, dort liegt keine style.css. Erste Meldung.
  • theme/style.css plus README.md an der Wurzel: zwei Einträge oben, geprüft wird die Archivwurzel. Erste Meldung.
  • style.css direkt an der Wurzel neben weiteren Dateien: wird nach dem Quelltext gefunden.
Messung und Randfälle: Quelle und Fundstellen
  • Der allgemeine Satz steht in class-wp-upgrader.php (Zeile 205), die Ursache in class-theme-upgrader.php (Zeilen 585 und 610).
  • Quelle ist der WordPress-Quelltext im Tag 7.1.3, abgerufen am 12.10.2026.
  • check_package stimmt in den Zeilen 560 bis 640 mit trunk überein (Commit 35e6ce2); andere Versionen wurden nicht verglichen.
  • Nicht in einer laufenden WordPress-Installation nachgestellt, nur aus dem Quelltext gelesen.
  • Mit WP-CLI läuft derselbe Installer; die Konsolenausgabe ist nicht nachgemessen.

Der WP-CLI-Aufruf:

wp theme install theme.zip

Wie finde ich die Ursache im ZIP?

Ersetzen Sie theme.zip durch Ihre Datei. Die Befehle sind auf macOS mit Test-Archiven ausgeführt; mit Info-ZIP-unzip auf Linux sollten sie gleich laufen (dort nicht ausgeführt).

1. Wo liegt die style.css?

unzip -Z1 theme.zip | grep 'style.css$' | grep -v '^__MACOSX/'

Der zweite Filter entfernt macOS-Zeilen (Finder-Archive führen sonst zusätzlich __MACOSX/theme/._style.css). Sie lesen die Schrägstriche im Pfad ab:

  • Genau einer (theme/style.css) ist der Normalfall.
  • Zwei oder mehr (theme-main/theme/style.css) bedeuten eine Ebene zu tief.
  • Keiner (style.css) bedeutet: an der Wurzel.

2. Wie viele Einträge hat die oberste Ebene?

unzip -Z1 theme.zip | cut -d/ -f1 | sort -u

Jede Ausgabezeile ist ein Eintrag der obersten Ebene. Eine Zeile mit dem Ordnernamen ist der Normalfall.

Zwei oder mehr Zeilen bedeuten: Die Archivwurzel gilt als Theme, style.css muss dann dort liegen (Befehl 1 zeigt style.css ohne Schrägstrich). Liegt sie nur in einem Unterordner (theme/style.css), kommt die erste Meldung.

Punktdateien wie .DS_Store zählen mit, __MACOSX nicht.

3. Hat die style.css einen Kopf?

unzip -p theme.zip theme/style.css | head -c 8192 | grep -i -E '^[[:blank:]/*#@]*Theme Name:'

Nehmen Sie den Pfad aus Schritt 1 und lesen Sie ab, ob eine Zeile „Theme Name:“ mit Namen ausgegeben wird. Keine Ausgabe heißt: zweite Meldung zu erwarten.

Der Befehl bildet die Suche nur annähernd nach (ohne ein führendes <?php).

Und unter Windows?

Dieser Befehl zeigt alle Pfade:

tar -tf theme.zip

Die Prüfungen 1 und 2 lesen Sie dort von Hand an der Liste ab. tar gehört seit Windows 10 zum System (Microsoft, 18.01.2018: ab Insider-Build 17063).

Wie behebe ich es?

Was, wenn das Theme eine Ebene zu tief liegt?

Bei theme-main/theme/style.css: Entpacken Sie das Archiv und packen Sie den Ordner neu, der style.css direkt enthält, als einzigen Eintrag der obersten Ebene:

unzip theme.zip -d entpackt
cd entpackt/theme-main
zip -r ../../theme-neu.zip theme

Schreiben Sie in ein neues Archiv (theme-neu.zip darf noch nicht existieren) oder löschen Sie das alte zuerst. Im Test (Info-ZIP-zip 3.0 auf macOS) hat dieselbe Aufrufform ein vorhandenes ZIP aktualisiert und Einträge behalten, die im Ordner nicht mehr lagen: Ein früheres README.md blieb an der Wurzel stehen.

Was, wenn weitere Dateien an der Wurzel liegen?

Verschieben Sie README.md und alles Weitere in den Theme-Ordner oder lassen Sie es weg, und packen Sie neu. Das gilt auch für Punktdateien wie .DS_Store: WordPress listet versteckte Dateien mit (class-wp-upgrader.php, Zeile 566).

Wie packe ich richtig?

Packen Sie den Ordner, nicht dessen Inhalt, und löschen Sie ein altes ZIP vorher.

rm -f theme.zip
zip -r theme.zip theme

Unter Windows 10 und neuer entsprechend:

tar -a -c -f theme.zip theme

Der Befehl schrieb auf macOS (bsdtar) ein vorhandenes ZIP neu, Windows ist nicht gemessen.

Was passiert, wenn ich aus dem Ordner heraus packe?

Ein Archiv, das so gepackt wird, führt index.php und style.css an der Wurzel, nicht theme/...:

cd theme && zip -r ../theme.zip .

Was, wenn der Kopf fehlt oder falsch ist?

Die style.css braucht am Anfang einen Kommentar mit mindestens dieser Zeile samt Wert:

/*
Theme Name: Mein Theme
*/

Für WordPress genügt Theme Name; mitten in einer Zeile, jenseits der ersten 8 KB oder ohne Wert wird sie nicht erkannt.

Prüfen Sie das neue ZIP mit den drei Befehlen. Ohne index.php folgt die Meldung aus Punkt 5.

Was nimmt mir der ZIP-Builder ab?

Alles Beschriebene geht mit Bordmitteln. Als Abkürzung gibt es den ZIP-Builder: Er packt Dateien und Ordner im Browser zu einem ZIP, ohne sie hochzuladen. Mit der Zielplattform „WordPress-Theme“ meldet er, ob eine style.css genau eine Ordnerebene unter der Wurzel liegt und ob darin „Theme Name:“ vorkommt. Die Prüfung ist nicht deckungsgleich mit der von WordPress:

  • Sie meldet ein Archiv mit style.css direkt an der Wurzel als Fehler, obwohl WordPress es nach dem Quelltext annimmt.
  • Sie bemerkt nicht, wenn neben dem Theme-Ordner weitere Dateien oder Ordner an der Wurzel liegen (mit einem zweiten Ordner gemessen).
  • Sie sucht „Theme Name:“ irgendwo in der Datei statt am Zeilenanfang in den ersten 8 KB.

Was ist mit dem Hinweis zum gemeinsamen Ordner?

Der Hinweis des ZIP-Builders, die ganze Auswahl liege unter einem gemeinsamen Ordner und die meisten Plattformen erwarteten die Dateien an der Wurzel, erscheint für alle Zielplattformen. Bei einem Theme folgen Sie ihm nicht: Nach dem Entfernen der Ebene liegt style.css an der Wurzel, und das meldet das Werkzeug selbst als Fehler. WordPress lehnt auch ein solches Archiv nicht ab, bildet den Ordnernamen dann aber aus dem ZIP-Dateinamen.

Das Ergebnis ersetzt die Kontrolle aus „Wie finde ich die Ursache im ZIP?“ nicht, es verkürzt sie.

Lassen Sie uns sprechen

Kostenlose Erstberatung - kein Verkaufsgespräch, sondern ehrliche Einschätzung.

Beratungsgespräch anfragen →