How to install a WordPress theme without breaking it

You bought a theme, downloaded the ZIP, and WordPress replied with “The package could not be installed.” Or the install worked and your site looks nothing like the demo. Both are common, and both have plain causes.

WordPress has three ways to install a theme: from the WordPress.org directory, by uploading a ZIP, or by copying the theme folder to the server. Each route ends the same way, with a valid theme folder inside /wp-content/themes/. This guide covers each route, what each error means, and what to check once the theme is live. If you are choosing between themes, start with how to choose WordPress templates for business.

What to do before you install anything

Take a backup of the files and the database, and make sure you know how to restore it. A backup you have never restored is a hope, not a plan. Our explainer on what a backup plugin actually covers explains why “full backup” does not always mean full.

Then check four things:

• Compatibility. Compare the WordPress and PHP versions the theme supports with what your site runs. On a store, check the WooCommerce version too.
• What the current theme provides. Write down your menus, widgets, custom CSS, homepage settings and any theme shortcodes. A new theme may not carry them over.
• Where to test. WordPress.org’s theme documentation recommends a test site for proper testing. On a live business site, use your host’s staging copy if it has one.
• Access. Make sure you have SFTP or file-manager access. If an activation takes the dashboard down, that is how you get back in.

How to install a theme from the WordPress directory

Use this route for free themes listed on WordPress.org. You need an administrator account.

1. Go to Appearance → Themes and click Add New Theme.
2. Search by name, or filter by feature.
3. Click Preview to see the theme with sample content.
4. Click Install.
5. Click Live Preview to see it with your own content. On a block theme, the preview opens in the Site Editor.
6. Click Activate when you are ready for visitors to see it.

If you clicked Install and nothing changed, that is expected. Installing makes a theme available. Activating makes it live. You can leave a theme installed and inactive until it is ready.

How to upload a premium theme from a ZIP

Themes from marketplaces and independent developers arrive as a download. The catch is that the download is often a bundle: documentation, licence files, a child theme, and the real theme ZIP inside it.

1. Unzip the download on your computer. Do not upload anything yet.
2. Find the installable theme ZIP. It is usually named after the theme. Some marketplaces let you download the installable theme file on its own, so check before you dig through the bundle.
3. In WordPress, go to Appearance → Themes → Add New Theme → Upload Theme.
4. Choose the theme ZIP, still zipped, and click Install Now.
5. Preview it, then activate.

Upload it under Themes, not Plugins. A theme ZIP uploaded at Plugins → Add New gets “No valid plugins were found.” If the theme needs companion plugins, such as a builder or a demo importer, install them after the theme. Our guide to installing a WordPress plugin safely covers that step.

How to install a theme manually with SFTP or WP-CLI

Use this route when the dashboard upload is blocked by a size limit, or when you want to see the files yourself.

1. Unzip the theme ZIP on your computer.
2. Connect with SFTP or open your host’s file manager.
3. Upload the theme folder to /wp-content/themes/. Do not use /wp-content/uploads/, which is for media.
4. Check the nesting. You want /wp-content/themes/theme-name/style.css, not /wp-content/themes/theme-name/theme-name/style.css.
5. Go to Appearance → Themes. The theme should now appear there. Activate it.

The difference between the routes trips people up. The dashboard uploader wants the ZIP. SFTP wants the unzipped folder.

Developers and anyone managing several sites can use WP-CLI. It accepts a directory slug, a local ZIP or a URL, and --activate is optional:

wp theme install twentytwentyfive
wp theme install ../my-theme.zip --activate

What a correct install looks like

The theme appears in Appearance → Themes with its screenshot and name. Inside its folder, WordPress’s Theme Handbook expects a style.css plus index.php for a classic theme, or style.css plus templates/index.html for a block theme. If those files are missing or sit one folder too deep, WordPress will not recognise the theme.

Why the install failed, and what each error means

Read the exact error before you try again. Each message points at a different cause, and only the first is about the file itself.

“The theme is missing the style.css stylesheet”

The full message is “The package could not be installed. The theme is missing the style.css stylesheet.” In practice this is almost always the outer marketplace bundle, not the theme. It can also be a plugin ZIP, a theme built for another platform, or a broken package. Upload the inner theme ZIP instead. Do not create a style.css by hand to get past the error. If the real theme ZIP still fails, ask the developer for a working copy.

“The uploaded file exceeds the upload_max_filesize directive in php.ini”

Your host caps the upload size. First, make sure you are not uploading the whole bundle, which is often what makes the file too big. Then open Tools → Site Health → Info and look under Media handling and Server to see the limit. Ask your host to raise it, or install over SFTP, which skips the limit.

“Could not create directory”

WordPress cannot write to /wp-content/themes/. Site Health → Info → Filesystem Permissions shows which directories are writable. WordPress’s handbook gives 755 for directories and 644 for files as a common setup, and notes that the right values depend on your host. It also warns against 777. World-writable files are a security risk, and wrong permissions can take a site offline. Ask your host to fix the ownership instead.

“Destination folder already exists”

A folder with that name is already in /wp-content/themes/. Either the theme is already installed, or an earlier install failed halfway. Check Appearance → Themes first. If WordPress offers to replace the current version with the upload, that is the clean route. Otherwise, take a backup, then rename or remove the leftover folder over SFTP and reinstall. Make sure it is not the active theme, or the parent of your active child theme.

No “Add New” or “Upload Theme” button

This is about your account, not your file. On Multisite, only the Super Admin has the install_themes capability, so ask whoever runs the network. Our Multisite installation guide explains how that split works. On WordPress.com, whether you can upload a theme depends on your plan. Some hosts also turn off uploads.

How to install a child theme

A child theme holds your custom code, so a parent theme update cannot overwrite it. The parent has to be installed but does not need to be active. Install the parent, install the child the same way, and activate only the child. The child’s style.css names its parent in a Template: line. If you delete the parent, the child stops working.

If you change theme code, do it in the child theme, never in the parent’s files. Our guide to theme customization that survives updates shows what belongs where.

What to check after you activate

The “New theme activated” notice means the switch happened. It does not mean the site works. Go through it the way a visitor would.

• Menus and widgets. Each theme defines its own menu locations and widget areas, so items can end up unassigned. Reassign them under Appearance → Menus or in the Site Editor.
• The demo look. Activating a theme does not import its demo. Demo content usually needs the theme’s own importer. A generic WordPress XML export will not rebuild it. Run any importer on staging first, because it writes pages and settings into your site.
• Theme features. Shortcodes, sliders and builder layouts from the old theme may now show as raw text or disappear.
• Forms and mobile. Submit every form. Check the menu on a real phone.
• Accessibility. Tab through the header and menus with the keyboard. Check that focus is visible and that text has enough contrast.
• Search visibility. If you built the site on staging, make sure production is not still set to noindex. Google’s documentation says a noindex tag keeps pages out of Search results. If URLs changed, add redirects.
• Speed. Test your real pages, not the demo. Starter templates can add a lot of weight.

On a WooCommerce store, WooCommerce’s theme guide says to test My Account, cart and checkout rather than trusting the demo. WooCommerce → Status lists the theme’s template overrides and flags any that are out of date. If something breaks, switch to Storefront on staging. If the problem goes away, the theme is the cause.

Installing the theme is usually the smallest part of a redesign. Configuration, content and testing are the rest. If you would rather hand that part off, SiteSelf’s page on design changes to an existing site covers what the agent does with styles and templates.

When to stop and get help

If the site goes blank or shows a fatal error after activation, do not keep clicking. WordPress Recovery Mode, available since version 5.2, emails the site admin a link that can get you back into the dashboard. If that email never arrives, connect over SFTP and rename the new theme’s folder. WordPress then falls back to an installed default theme. The white screen guide walks through the rest.

Change one thing at a time, and write down the exact error before you contact the theme developer or your host. Hand the job over if the error names a server setting you cannot reach, the store’s checkout fails on the new theme, or the fix means editing the theme’s PHP and you do not have a staging copy to try it on.