The theme is missing the style.css stylesheet: why WordPress rejects a theme ZIP
Which error message does WordPress show?
Uploading a theme ZIP in the WordPress admin stops with one of two messages. On an English 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.
On a German installation the same message reads:
Das Paket konnte nicht installiert werden. Dem Theme fehlt das Stylesheet style.css.
The second message is about a style.css without a usable header:
The package could not be installed. The style.css stylesheet does not contain a valid theme header.
Why is it missing when it is in the ZIP?
The message sounds as if there were no style.css. What is checked is the place, not whether the file exists in the archive: one level too deep is reported exactly like missing.
A new style.css changes nothing: the file was there, just not where WordPress looks. With the second message the structure is fine and the header is the problem.
What does WordPress check when it unpacks?
- Unpacking. WordPress does not extract a
__MACOSX/entry at the root (file.php). - Which folder is the theme? If the top level of the unpacked archive consists of exactly one entry and that entry is a folder, its contents are the theme. With several entries or a single file, the archive root itself is the theme and the folder name is derived from the ZIP file name.
- Is there a style.css? It must be in exactly that folder, otherwise you get the first message.
- Is there a header? WordPress reads only the first 8 KB of the file and looks for a line that begins (after any number of spaces, tabs and the characters
/ * # @) withTheme Name:, case-insensitive. Without that line or a value, you get the second message. - After that WordPress requires an
index.php,templates/index.htmlorblock-templates/index.htmlunless aTemplate:header (child theme) is present. If it is missing, the general sentence is followed by a detail text that begins with “Template is missing.”
What does that mean for typical archives?
theme-main/theme/style.css:theme-main/is checked and has no style.css. First message.theme/style.cssplus one more file at the root, such asREADME.md: two top-level entries, so the archive root is checked. First message.style.cssdirectly at the root next to other files: found, according to the source code.
Measurement and edge cases: source and line references
- The general sentence is in
class-wp-upgrader.php(line 205), the cause inclass-theme-upgrader.php(lines 585 and 610). - Source: the WordPress code at tag 7.1.3, retrieved 12 October 2026.
check_packageis identical in lines 560 to 640 totrunk(commit 35e6ce2); other versions were not compared.- Not reproduced in a running WordPress installation, only read from the source.
- With WP-CLI the same installer runs; its console output was not measured.
The WP-CLI call:
wp theme install theme.zip
How do I find the cause in the ZIP?
Replace theme.zip with your file. The commands were run on macOS with test archives; on Linux they should behave the same (not run there).
1. Where is style.css?
unzip -Z1 theme.zip | grep 'style.css$' | grep -v '^__MACOSX/'
The second filter drops macOS lines (Finder archives otherwise also list __MACOSX/theme/._style.css). Read the slashes in the path:
- One (
theme/style.css) is normal. - Two or more (
theme-main/theme/style.css) mean one level too deep. - None (
style.css) means the root.
2. How many entries does the top level have?
unzip -Z1 theme.zip | cut -d/ -f1 | sort -u
Each output line is one top-level entry; one line with the folder name is the normal case.
Two or more mean the archive root is treated as the theme, so style.css must lie there (command 1 shows style.css without a slash). If it lies only in a subfolder (theme/style.css), you get the first message.
Dotfiles such as .DS_Store count, __MACOSX does not.
3. Does style.css have a header?
unzip -p theme.zip theme/style.css | head -c 8192 | grep -i -E '^[[:blank:]/*#@]*Theme Name:'
Use the path from step 1 and read whether a line “Theme Name:” with a name is printed; no output means expect the second message. It only approximates the WordPress search (no leading <?php).
What about Windows?
This command lists all paths:
tar -tf theme.zip
Read steps 1 and 2 from that list by hand. tar ships with Windows 10 since Insider build 17063 (Microsoft, 18 January 2018).
How do I fix it?
What if the theme sits one level too deep?
For theme-main/theme/style.css: unpack the archive and repack the folder that contains style.css directly, as the only top-level entry:
unzip theme.zip -d unpacked
cd unpacked/theme-main
zip -r ../../theme-new.zip theme
Write to a new archive (theme-new.zip must not exist yet) or delete the old one first. In the test (Info-ZIP zip 3.0 on macOS), the same command form updated an existing ZIP and kept entries that were no longer in the folder: an earlier README.md stayed at the root.
What if more files sit at the root?
Move README.md and anything else into the theme folder or leave it out. Dotfiles such as .DS_Store count too: WordPress lists hidden files (class-wp-upgrader.php, line 566).
How do I pack correctly?
Pack the folder, not its contents, and delete an old ZIP first.
rm -f theme.zip
zip -r theme.zip theme
On Windows 10 and later, the equivalent is:
tar -a -c -f theme.zip theme
On macOS (bsdtar) the command rewrote an existing ZIP; Windows was not measured.
What happens if I pack from inside the folder?
An archive packed like this lists index.php and style.css at the root, not theme/...:
cd theme && zip -r ../theme.zip .
What if the header is missing or wrong?
style.css needs a comment at the top with at least this line, including a value:
/*
Theme Name: My Theme
*/
For WordPress, Theme Name is enough; in the middle of a line, beyond the first 8 KB or without a value it is not recognised.
Check the new ZIP with the three commands. Without an index.php, point 5 applies.
What does the ZIP Builder take off my hands?
Everything above works with built-in tools. As a shortcut there is the ZIP Builder: it packs files and folders into a ZIP in the browser without uploading them. With the target platform “WordPress Theme” it reports whether a style.css sits exactly one level below the root and contains “Theme Name:”. The check is not identical to WordPress:
- It reports an archive with style.css directly at the root as an error although WordPress accepts it according to the source code.
- It does not notice other files or folders at the root next to the theme folder (measured with a second folder).
- It looks for “Theme Name:” anywhere in the file instead of at the start of a line within the first 8 KB.
What about the hint about the shared folder?
The ZIP Builder’s hint that the whole selection sits under one shared folder, while most platforms expect the files at the root, appears for every target platform. For a theme do not follow it: after removing the level, style.css sits at the root, and the tool itself reports that as an error. WordPress does not reject such an archive either, but would derive the folder name from the ZIP file name.
The result shortens the check under “How do I find the cause in the ZIP?” but does not replace it.