How to Get a WordPress Theme into the WordPress.org Theme Directory

17/08/2026 · Wordpress

Building a WordPress theme that works on your own website is one thing. Building one that is ready for the official WordPress.org Theme Directory is a very different exercise.

The directory is not simply a place where you upload a ZIP file and wait for someone to click “Approve”. A public theme needs to work across environments you do not control, follow WordPress coding and security practices, respect licensing requirements, stay out of plugin territory, support accessibility basics and behave like a good citizen inside WordPress.

I think of the submission process as a release engineering exercise rather than an administrative task. If you design for the directory requirements from the beginning, submission becomes relatively straightforward. If you try to retrofit compliance onto a finished theme, you can easily spend more time fixing the release than building it.

This guide walks through the process I use when preparing a WordPress theme for public distribution, based on the current WordPress.org Themes Team requirements.

1. Why Publish a Theme on WordPress.org?

You do not need WordPress.org to distribute a WordPress theme. You can publish it on GitHub, distribute it from your own website or sell it through another platform.

However, the official Theme Directory provides several advantages that are difficult to reproduce independently:

• Distribution: users can discover and install your theme directly from the WordPress admin.
• Trust: inclusion demonstrates that the theme has passed the WordPress.org review process.
• Automatic updates: new releases can be delivered through the normal WordPress update system.
• Support infrastructure: the theme receives its own WordPress.org support forum.
• Visibility: WordPress.org can expose your work to users who would never discover your own website.
• Developer credibility: maintaining a public theme demonstrates considerably more than displaying screenshots in a portfolio.

For me, that last point is particularly important. A production theme in the directory demonstrates that you can build software to somebody else’s standards, not just make a design look correct on a controlled installation.

You can see the WordPress themes I publish through the OZ Web Expert free WordPress themes collection.

2. Understand the Rules Before You Write the Theme

The single best way to make theme approval easier is to read the official requirements before finishing development.

The Themes Team currently groups the requirements into areas including:

• licensing and copyright;
• privacy;
• accessibility;
• code quality and security;
• theme functionality;
• plugin territory;
• theme naming and trademarks;
• internationalisation;
• files and packaging;
• classic-theme requirements;
• block-theme requirements;
• admin pages and onboarding;
• credits, commercial links and upselling.

The important point is that WordPress.org is reviewing a general-purpose public software package, not your personal website.

A technique that is perfectly acceptable in a private client theme may therefore be inappropriate for a directory theme.

3. Classic Theme or Block Theme?

Before packaging anything, be clear about which type of theme you are submitting.

The review requirements overlap heavily, but the required files and implementation details differ.

If you are developing a classic theme, understanding the template hierarchy is essential. I have covered one common source of confusion separately in WordPress Template Hierarchy for the Home Page.

4. Prepare the Required Theme Files

A clean theme package might look something like this for a classic theme:

my-theme/
├── assets/
│   ├── css/
│   ├── fonts/
│   ├── images/
│   └── js/
├── inc/
├── template-parts/
├── 404.php
├── archive.php
├── comments.php
├── footer.php
├── functions.php
├── header.php
├── index.php
├── page.php
├── readme.txt
├── screenshot.png
├── single.php
└── style.css

A basic block theme will look different:

my-block-theme/
├── assets/
├── parts/
├── patterns/
├── styles/
├── templates/
│   └── index.html
├── readme.txt
├── screenshot.png
├── style.css
└── theme.json

For a block theme, WordPress.org specifically requires style.css, readme.txt, theme.json and templates/index.html.

The package should contain the files needed to run the theme — not your entire development repository.

5. Get style.css Right

The header in style.css is effectively your theme’s identity card.

A realistic example looks like this:

/*
Theme Name: OZ Personal
Author: Grigory Frolov
Author URI: https://ozwebexpert.com/
Description: A clean, lightweight WordPress theme for personal websites, portfolios and professional blogs.
Version: 1.0.0
Requires at least: 6.5
Tested up to: 6.9
Requires PHP: 8.0
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: oz-personal
*/

Do not treat this header as decorative metadata. WordPress.org uses several of these values when processing the theme.

The current required fields include:

• Theme Name
• Author
• Description
• Version
• Requires at least
• Tested up to
• Requires PHP
• License
• License URI
• Text Domain

Your text domain should match the theme slug, which should also match the theme directory name.

Consistency matters. Do not use one name for the folder, another for the text domain and a third variation for function prefixes.

6. Create a Proper readme.txt

A valid readme.txt is required.

At minimum, use it to document what the theme is, licensing information, important setup instructions, resources and the changelog.

=== OZ Personal ===
Contributors: gynsus
Requires at least: 6.5
Tested up to: 6.9
Requires PHP: 8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A lightweight personal WordPress theme for portfolios and professional blogs.

== Description ==

OZ Personal is a clean, responsive WordPress theme designed for personal websites, portfolios and content-focused blogs.

== Changelog ==

= 1.0.0 =
* Initial release.

== Resources ==

Inter font
Copyright 2016 The Inter Project Authors
Licensed under the SIL Open Font License 1.1
https://github.com/rsms/inter

The Resources section is particularly useful because it gives reviewers one place to verify third-party fonts, libraries and images.

7. Audit Every Asset for GPL-Compatible Licensing

Licensing is one of the areas where otherwise solid themes get into trouble.

It is not enough for your PHP files to be GPL.

Everything distributed inside the theme ZIP must be compatible with the GPL.

That can include:

• PHP;
• JavaScript;
• CSS;
• fonts;
• icons;
• stock photographs;
• placeholder images;
• SVG files;
• third-party libraries.

This means that a stock image which you legally purchased for a website is not automatically acceptable for redistribution inside a GPL WordPress theme.

For every third-party resource, document:

1. what it is;
2. who created it;
3. its licence;
4. where the original resource can be found.

I keep this explicit across OZ Web Expert as well. You can read the site’s WordPress theme and plugin GPL licensing statement for an example of how I handle distributed WordPress products.

8. Keep Plugin Functionality Out of the Theme

This is probably the conceptual rule that catches the most developers.

A theme controls presentation. A plugin provides site functionality.

If switching themes would make important content or business functionality disappear, that functionality probably belongs in a plugin.

WordPress.org specifically prevents themes from including custom post types, custom blocks, shortcodes and other functionality unrelated to presentation.

This separation is good architecture anyway. A business should not lose its structured content simply because someone changes the design.

There are edge cases. For example, extending the presentation or metadata of a WordPress navigation menu can legitimately be connected to a theme. I demonstrate one such technique in How to Add Custom Fields to WordPress Menu Items.

9. Review Security, Escaping and Sanitisation

Security problems are serious review blockers.

At a minimum, think about data at two boundaries:

• Input: validate and sanitise data before storing it.
• Output: escape data for the context where it is displayed.

For example:

$title = isset( $_POST['oz_personal_title'] ) ? sanitize_text_field( wp_unslash( $_POST['oz_personal_title'] ) ) : '';
update_option( 'oz_personal_title', $title );

And when outputting it:

<h2><?php echo esc_html( get_option( 'oz_personal_title' ) ); ?></h2>

Do not assume that because data came from WordPress admin it is safe to print raw.

Also check for:

• PHP warnings and notices;
• JavaScript errors;
• deprecated WordPress functions;
• incorrect capability checks;
• missing nonces where an action requires them;
• unescaped URLs and attributes;
• unvalidated settings.

Anything your theme exposes in the global PHP namespace should also use a unique prefix. WordPress.org currently requires prefixes to be at least four characters long.

10. Check Accessibility Before Submission

Accessibility is not limited to themes using the accessibility-ready tag.

All submitted themes have baseline accessibility requirements.

Among the essentials:

• provide a skip link when there is navigation or other content to skip;
• make keyboard focus visible;
• make interactive controls keyboard-accessible;
• do not create navigation that only works with a mouse;
• use semantic HTML where possible;
• maintain sensible colour contrast;
• avoid breaking browser zoom or text resizing.

A simple skip link might look like:

<a class="skip-link screen-reader-text" href="#primary">
	<?php esc_html_e( 'Skip to content', 'oz-personal' ); ?>
</a>

Then test the site without touching your mouse.

Press Tab from the top of the page and ask:

• Can I see where focus is?
• Can I open and close the mobile menu?
• Can I reach every important link?
• Can I operate buttons and controls?

If the answer is no, fix it before submission.

11. Remove Unexpected External Requests and Tracking

A public WordPress.org theme should not silently send information to your servers or load arbitrary remote resources.

The general principle is simple: external communication must not surprise the user.

WordPress.org requires tracking and collection of user data to be disabled by default and opt-in.

The requirements also restrict fetching remote resources without explicit user consent.

This means you should carefully inspect:

• analytics code;
• CDN-hosted libraries;
• remote JavaScript;
• API calls to your website;
• tracking pixels;
• affiliate links;
• remote onboarding content.

Where practical, ship required assets with the theme itself.

This also makes the theme more predictable and resilient. A theme should not suddenly break because a third-party CDN changes a URL.

12. Make the Theme Translation-Ready

Public-facing strings in PHP should use WordPress internationalisation functions rather than hard-coded English.

Instead of:

<button>Read more</button>

use:

<button>
	<?php esc_html_e( 'Read more', 'oz-personal' ); ?>
</button>

The text domain should match your theme slug:

Text Domain: oz-personal

and:

esc_html_e( 'Read more', 'oz-personal' );

Do not mix several variations of the text domain throughout the codebase.

13. Prepare the Theme Screenshot

Your screenshot.png is the theme’s shop window in the directory.

But WordPress.org does not want it to become an advertisement.

The current requirements specify that the screenshot:

• must not look like an advertisement;
• must use a 4:3 width-to-height ratio;
• must not exceed 1200 × 900 pixels.

I would recommend showing the theme itself rather than creating a poster full of feature labels such as:

FAST! SEO READY! PRO FEATURES! BUY NOW!

A clean screenshot of a realistic website communicates far more.

14. Test the Theme Like Someone Else Built It

This is where having a reproducible local WordPress installation becomes extremely useful.

I use isolated development environments so I can install a theme from scratch rather than relying on months of accumulated settings from the original development site.

If you need a reproducible local setup, see my guide on how to install WordPress locally using Docker.

Before submission, I would test at least:

• a completely fresh WordPress install;
• theme activation;
• front page;
• posts page;
• single posts;
• pages;
• archives;
• search results;
• 404 page;
• long titles;
• very long words and URLs;
• images with different aspect ratios;
• galleries;
• lists and nested lists;
• tables;
• comments;
• pagination;
• mobile navigation;
• keyboard navigation;
• light and dark colour combinations if supported;
• WordPress debug mode.

I also test with:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );

A clean browser window does not mean your PHP error log is clean.

15. Run Theme Check — But Do Not Rely on It Alone

The WordPress Theme Check plugin can detect many common problems before submission.

Install it on your development site, activate your theme and run the checks.

However, there is an important 2026 caveat: the WordPress.org plugin page currently warns that Theme Check has not been tested against the latest three major WordPress releases.

So I would use Theme Check as one layer of testing, not as the final authority.

The current Theme Review Requirements should remain your primary checklist.

My approach is:

1. Read the current Theme Review Requirements.
2. Run Theme Check.
3. Fix genuine errors and investigate warnings.
4. Run PHP and JavaScript debugging.
5. Manually test functionality and accessibility.
6. Perform a final licensing audit.

Passing an automated scan does not guarantee that a theme is ready for the directory.

16. Clean and Package the Release ZIP

Before creating the final ZIP, remove anything that belongs to your development environment rather than the released product.

Examples include:

• .git/;
• .svn/;
• IDE project files;
• debug logs;
• database dumps;
• development ZIP files;
• macOS __MACOSX directories;
• Windows Thumbs.db files;
• unused source assets;
• code intended only for a paid version.

Do not accidentally package your entire project directory.

The final archive should unpack directly into a single theme directory:

oz-personal.zip
└── oz-personal/
    ├── style.css
    ├── readme.txt
    ├── ...

Not:

oz-personal.zip
└── release/
    └── final/
        └── oz-personal/

Before uploading, install the exact ZIP you plan to submit onto a clean WordPress instance.

This catches packaging errors that are invisible when you work directly from your Git repository.

17. Upload the Theme to WordPress.org

Once the release package is ready:

1. Create or log in to your WordPress.org account.
2. Open the official theme upload page.
3. Upload the theme ZIP.
4. Review any automated results.
5. Fix problems if the package does not pass the initial checks.
6. Resubmit when necessary.

The official upload page is:

WordPress.org Theme Upload

There is an important submission restriction: theme authors may have only one new theme in the review queue at a time. Updates to themes already in the directory are treated separately.

Do not submit five unfinished themes hoping reviewers will tell you which one is acceptable.

18. What Happens During Theme Review?

After your theme is uploaded, it enters the WordPress.org theme review process.

The general workflow is:

1. The theme is uploaded.
2. It enters the new-theme queue.
3. A reviewer is assigned.
4. The reviewer checks the required items and records issues.
5. You update the theme if changes are required.
6. Once requirements are satisfied, the reviewer can approve it.
7. The theme then receives a final review.
8. If no blocking problems remain, it is marked live.

Do not expect a guaranteed approval date. The Themes Team explicitly states that there are no exact queue timeframes because review capacity depends on volunteer availability.

The fastest thing you can control is your own response time.

When a reviewer identifies a problem:

• read the entire review before changing code;
• understand the rule behind the request;
• fix the underlying issue rather than hiding the warning;
• upload a clean new version;
• reply clearly and professionally.

WordPress.org also notes that a ticket with no update from the theme author for seven days may be closed due to inactivity.

19. Common Reasons Themes Fail Review

Most failures are not caused by sophisticated WordPress problems. They are caused by avoidable release mistakes.

The current requirements also warn that themes with three or more distinct issues may be closed as not approved, although the author can correct the problems and submit again.

That is another reason to do your own review before asking a volunteer reviewer to find your bugs.

20. My Pre-Submission Workflow

If I were preparing a theme for WordPress.org today, this would be my release sequence.

Phase 1: Architecture

• Confirm whether the theme is classic or block-based.
• Separate theme presentation from plugin functionality.
• Choose the final theme name, slug, prefix and text domain.

Phase 2: Code review

• Check sanitisation.
• Check escaping.
• Check capabilities and nonces.
• Remove deprecated APIs.
• Test with WP_DEBUG.
• Check JavaScript console errors.

Phase 3: UX and accessibility

• Test keyboard navigation.
• Test mobile navigation.
• Check focus states.
• Check contrast.
• Check long and unusual content.

Phase 4: Compliance

• Audit every bundled asset licence.
• Review remote requests.
• Check translation functions.
• Check style.css.
• Check readme.txt.
• Check screenshot.png.

Phase 5: Automated testing

• Run Theme Check.
• Review the results manually.
• Run additional coding-standard checks where appropriate.

Phase 6: Release test

• Create the production ZIP.
• Create a fresh WordPress installation.
• Install from the ZIP.
• Activate the theme.
• Test the primary site flows again.

Phase 7: Submission

• Upload to WordPress.org.
• Review automated feedback.
• Monitor the review ticket.
• Respond to reviewer feedback promptly.

This might sound slower than simply clicking Upload.

In practice, it is much faster.

The expensive workflow is upload → rejection → patch → upload → new issue → patch → upload.

21. What Happens After Your Theme Is Approved?

Approval is the beginning of maintaining a public theme, not the end.

Once the theme is live, users can install it through WordPress, and future releases can be distributed through the normal theme update mechanism.

From that point, you need to treat the theme as maintained software.

That means:

• testing against new WordPress releases;
• testing against supported PHP versions;
• fixing security problems quickly;
• maintaining the changelog;
• answering legitimate support questions;
• keeping documentation accurate;
• not introducing prohibited functionality in later updates.

A useful rule is this:

If you would be uncomfortable automatically installing your update on thousands of websites you cannot access, the release probably needs more testing.

22. Final Thoughts

Getting a theme into the WordPress.org directory is less about satisfying a reviewer and more about learning to build portable WordPress software properly.

The strongest themes are designed around a few straightforward principles:

• presentation stays in the theme;
• persistent functionality stays in plugins;
• user data is treated carefully;
• output is escaped and input is sanitised;
• interfaces work beyond a mouse and desktop screen;
• third-party assets have clear licences;
• the release package contains only what users actually need;
• updates are treated as software releases rather than ZIP replacements.

Follow those principles from the beginning and the WordPress.org review requirements stop feeling like arbitrary restrictions. Most of them simply enforce habits that make a theme safer, more portable and easier to maintain.

And that is valuable whether you are publishing a free theme for thousands of WordPress users or building a custom site for one Australian business.

If you want to see how I approach WordPress themes in practice, browse my free WordPress themes and other WordPress development articles.

Official WordPress Resources

• WordPress.org Theme Review Requirements
• WordPress.org Theme Review Process
• WordPress Theme Handbook: Publishing Themes
• WordPress Theme Testing Guide
• Theme Check Plugin
• Submit a Theme to WordPress.org