Fixing 'The package could not be installed. The theme is missing the style.css stylesheet' in WordPress

The Error

You go to Appearance → Themes → Add New → Upload Theme in wp-admin, pick your .zip file, click Install, and WordPress hits you with:

The package could not be installed. The theme is missing the style.css stylesheet.

The theme never installs. WordPress rejects the package outright — no partial files, no useful rollback message, just a dead stop.

Root Cause

WordPress looks for style.css in the root of the extracted zip. That file must exist and contain a valid theme header comment. Miss either condition and WordPress won't touch it.

Four things cause this in practice:

Wrong zip structure — the zip contains a wrapper folder, so WordPress extracts to my-theme/my-theme/style.css instead of my-theme/style.css.
GitHub source zip — "Download ZIP" from a repo often puts style.css inside a subdirectory like dist/ or src/, not at the root.
Missing theme header — style.css exists but lacks the required Theme Name: line in the comment block at the top.
Wrong folder zipped — you accidentally zipped the parent folder containing the theme folder, adding an extra nesting level.

Fix 1: Check and Correct the Zip Structure

Nine times out of ten, this is your problem. Before uploading anything, inspect what's actually inside the zip.

On macOS/Linux:

unzip -l my-theme.zip | head -20

On Windows, open the zip in File Explorer or 7-Zip and check the top-level contents.

What you want to see:

my-theme/
my-theme/style.css
my-theme/index.php
my-theme/functions.php
...

What causes the error (double-nested):

my-theme/
my-theme/my-theme/
my-theme/my-theme/style.css
my-theme/my-theme/index.php
...

Got double nesting? Repack the zip from the right folder:

# Extract the zip
unzip my-theme.zip

# Go into the actual theme folder
cd my-theme/my-theme

# Repack from inside — style.css ends up at the zip root
zip -r ../../my-theme-fixed.zip .

# Upload my-theme-fixed.zip

Fix 2: GitHub / Source Repository Zips

GitHub's "Download ZIP" bundles the entire repo — not just the theme. Many premium and open-source themes store the installable theme inside a subdirectory like theme/, dist/, or src/. You need to zip that subfolder, not the repo root.

Download and extract the GitHub zip.
Find the folder that has style.css directly inside it.
Zip that folder only:

# After extracting the GitHub zip:
ls repo-main/
# → dist/  src/  README.md  ...

ls repo-main/dist/
# → style.css  index.php  functions.php  ← this is what you want

cd repo-main/dist
zip -r ../../my-theme.zip .

# Now upload my-theme.zip

Also worth checking: some repos include a pre-built my-theme.zip inside the download. That's usually the one meant for WordPress — look for it before manually repacking anything.

Fix 3: Add or Fix the style.css Header

A style.css that exists but has no theme header is just as bad as a missing file. WordPress needs to read the header to register the theme. Open style.css and make sure the very top looks like this:

/*
Theme Name: My Theme
Theme URI: https://example.com/my-theme
Author: Your Name
Author URI: https://example.com
Description: A short description of the theme.
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-theme
*/

Technically, Theme Name: is the only required line. Everything else is optional — but filling it out is good practice. Add the header, rezip, upload again.

Fix 4: Install via FTP Instead

Tired of wrestling with the wp-admin uploader? Bypass it entirely with FTP/SFTP and drop the theme folder straight into wp-content/themes/:

# Connect via SFTP
sftp user@your-server.com

# Navigate to themes directory
cd /var/www/html/wp-content/themes/

# Upload the theme folder directly
put -r /local/path/to/my-theme .

Or with rsync if you prefer:

rsync -avz /local/path/to/my-theme/ user@your-server.com:/var/www/html/wp-content/themes/my-theme/

Once uploaded, head to Appearance → Themes in wp-admin. The theme will show up and you can activate it directly — no upload dialog needed.

Fix 5: WP-CLI (Fastest for SSH Access)

SSH access? WP-CLI is the cleanest option:

# Install from a local zip
wp theme install /path/to/my-theme.zip --activate

# Install from WordPress.org by slug
wp theme install twentytwentyfour --activate

# Check installed themes
wp theme list

WP-CLI also gives far more useful error output than wp-admin when something is still wrong with the package.

Verification

After fixing and uploading:

Go to Appearance → Themes — the theme card should appear with its name and screenshot.
Click Activate — the site should load with the new theme applied.
Visit the frontend and confirm the layout renders correctly.
Open Appearance → Customize and check it loads without errors.

Theme activates but the site looks broken? That's a separate problem — missing required plugins, a child theme without its parent, and so on. Not related to this upload error.

Prevention

Inspect before uploading — run unzip -l theme.zip | head -5 locally to confirm the structure is correct before touching wp-admin.
Download from the vendor dashboard, not GitHub — premium theme vendors package the installable zip correctly. GitHub source zips almost never are.
Automate your packing — building your own theme? A Makefile target ensures you always zip from the right directory:

# Example Makefile target
pack:
    cd .. && zip -r my-theme.zip my-theme/ --exclude "my-theme/.git/*" --exclude "my-theme/node_modules/*"
    mv my-theme.zip my-theme/dist/