The WordPress plugins directory reviewed more than 12,000 plugin submissions in 2025. A meaningful share of those took multiple attempts to get through. The rejection reasons were rarely creative: missing license headers, unescaped output, a readme that the review team had to read twice to figure out what the plugin actually did.
This guide covers the submission process from the beginning: what reviewers are actually checking, where most rejections happen, how to write a readme that passes review and shows up in search, and what to do in the first 30 days after approval to build real install momentum.
What the reviewers are actually checking
The WordPress.org review team is not looking for perfect code. They are looking for safe code that meets the published guidelines, will not surprise users, and can be maintained by someone other than you.
Four things get plugins rejected most often.
Security. Missing nonces on any form that changes data. Output that is not escaped with esc_html(), esc_attr(), esc_url(), or equivalent. Using $_POST or $_GET data directly without sanitization. The reviewers will find these. WordPress core has had these patterns baked in since 3.x and the expectation is that plugins use them.
Direct database queries. Writing raw SQL with mysql_query() or mysqli_query() instead of $wpdb. If you need a custom query that Drizzle or a WordPress query builder cannot handle, you run it through $wpdb->prepare() with placeholders. No exceptions. The reviewers will close your ticket and ask you to fix it.
Licensing. Every file in your plugin needs a license header. GPL v2 or later is the standard, and it must be compatible with WordPress's own license. This catches a lot of first submissions because developers copy license headers inconsistently across files, or forget them entirely in utility files added late in development.
<?php
/**
* Plugin Name: My Plugin
* Plugin URI: https://example.com/my-plugin
* Description: What it does in one sentence.
* Version: 1.0.0
* Author: Your Name
* Author URI: https://example.com
* License: GPL v2 or later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: my-plugin
* Domain Path: /languages
*/
That header goes in your main plugin file. Then each additional PHP file should carry a short license notice at the top.
Script and style enqueueing. Plugins that call wp_enqueue_script() without a version parameter, or that directly echo <script> tags instead of going through WordPress's enqueueing system, get flagged. The version parameter matters for cache busting and the reviewers will check it.
wp_enqueue_script(
'my-plugin-script',
plugin_dir_url( __FILE__ ) . 'js/main.js',
array( 'jquery' ),
MY_PLUGIN_VERSION, // defined constant, not hardcoded
true
);
Build artifacts and source files. If your plugin compiles JavaScript with Vite, webpack, Rollup, or any other build tool, you need to include the original source files alongside the compiled output. Reviewers enforce this under GPL: users must be able to access the actual source, not just a build artifact. Unminified compiled JavaScript does not satisfy this. Put your source files in a dedicated directory and mention them in your readme if the relationship is not obvious.
The review ticket will tell you specifically what to fix. Read the whole thing before replying, because the reviewer often catches multiple issues in a single pass and expects them all addressed before you resubmit.
The readme.txt requirements
The readme.txt is where most first-time submissions go wrong, and it matters for two reasons: it has to satisfy the review team's requirements, and it determines how your plugin shows up in WordPress.org search.
Required headers (your plugin will not be accepted without these):
=== My Plugin ===
Contributors: yourusername
Tags: forms, contact, email
Requires at least: 6.0
Tested up to: 6.7
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
The Tested up to field needs to reflect the WordPress version you have actually tested against. Set it to the current stable WordPress release. The Stable tag must match the version folder in your SVN repository exactly. Setting Stable tag: trunk is documented as working but the review team actively discourages it and some reviewers will ask you to change it.
The short description (the first paragraph after the headers, before the first == section heading) gets used in WordPress.org search results and category listings. It should say what the plugin does in plain English, in one or two sentences, with the relevant keyword near the front.
My Plugin adds a drag-and-drop contact form builder to WordPress with conditional logic and multi-step forms.
That is functional. It names the thing, names what it does, and includes words people search for.
Then the full == Description == section. This is the long-form landing page for your plugin. It should cover what it does, who it is for, the main features, and any limitations worth disclosing. Screenshots referenced in == Screenshots == render inline here on the WordPress.org listing page.
The == Installation == section is required and the review team checks for it. Two or three steps is fine. Include the short activation instructions.
== Frequently Asked Questions == is optional but contributes to search indexing on WordPress.org. Worth including.
== Changelog == is required and should have at least one entry for the initial release. Reviewers check that this exists.
How the submission process works
Go to wordpress.org/plugins/developers/add/ and fill in the form. You need a wordpress.org account. You submit the plugin as a ZIP file and provide a display name.
The review team gets it in their queue. They will read the code, check the readme, and either approve it or send back a ticket with specific issues to address. That ticket comes by email.
If they request changes, fix exactly what they asked about, then reply to the ticket. Do not resubmit a new ZIP without replying. The communication happens through the ticket.
When the plugin is approved, you get access to your SVN repository at https://plugins.svn.wordpress.org/your-plugin-slug/. This is where every release from now on goes.
The SVN structure looks like this:
your-plugin-slug/
├── trunk/ ← your development copy
└── tags/
└── 1.0.0/ ← matches Stable tag in readme.txt
For the initial release after approval:
# Check out the repository
svn co https://plugins.svn.wordpress.org/your-plugin-slug/ my-plugin-svn
# Copy your plugin files into trunk
cp -r my-plugin/* my-plugin-svn/trunk/
# Create the tag for your first release
svn cp my-plugin-svn/trunk my-plugin-svn/tags/1.0.0
# Add new files and commit
cd my-plugin-svn
svn add trunk/* tags/1.0.0/*
svn commit -m "Initial release 1.0.0"
WordPress.org will pick up the new tag within a few minutes. Your plugin will appear in search results shortly after.
Most teams do not want SVN as their daily version control. The practical approach is to keep your plugin in Git (GitHub, GitLab, wherever) and push to SVN only when releasing. 10up's action-wordpress-plugin-deploy GitHub Action automates this well. You tag a release in Git, the action builds the plugin and commits it to SVN. SVN becomes a deployment target, not a development tool.
Review timelines in 2026
AutomagicWP tracks more than 15,000 plugins and monitors new plugin first-appearance dates. Based on that data, the typical window between submission and approval in 2026 is two to four weeks.
That range is not uniform. The queue gets longer in Q1 (post-holiday surge) and around WordCamp US when a lot of developers finish projects and submit simultaneously. A clean first submission gets through faster. Submissions that require multiple rounds of review can stretch to six or eight weeks.
The review team posts queue status updates on make.wordpress.org/plugins. If you are past the expected window, check there before emailing. The team is small relative to submission volume.
To put a real number on it: I submitted Selektable, a small form selection utility, and the review came back in four days. There were 350+ plugins in the queue at the time. The plugin was compact with a straightforward codebase, which almost certainly helped.
A separate plugin went differently. The frontend was built with Svelte, and we shipped the compiled JavaScript unminified. Completely readable, no obfuscation. The reviewer pushed back anyway and asked for the actual .svelte source files. We went back and forth twice. The issue was GPL: compiled output, even when readable, does not satisfy the requirement that users can access and work with the source. Adding a src/ directory with the Svelte files to the ZIP got it through.
One thing that speeds things up consistently: reading the plugin guidelines before submitting. The reviewers are matching your code against those guidelines. Knowing them shortens the gap between what you submitted and what they need.
Plugin rankings and comparisons — done right
Track how your plugin performs over time, benchmark it against competitors, and spot trends before they move your install counts. Join the waitlist and be first in when it launches.
The first 30 days after approval
Most new plugin developers treat approval as the finish line. It is not. The first 30 days determine whether your plugin finds a trajectory or stays flat.
A few things to do immediately.
Fill in your assets. The assets/ directory in your SVN repository holds your plugin icon, banner, and screenshots. Plugins without a custom icon appear with a generic grey box in WordPress.org search results. That costs you clicks. The icon should be 128x128 and 256x256 (both sizes). The banner is 772x250 and 1544x500. Add these before anyone else finds your listing.
Write a proper plugin page. The == Description == section is your listing page. Treat it like a landing page. What does this plugin solve? Who is it for? What are the three things that make it worth installing over the alternative? Screenshots with real captions convert better than bullet lists.
Get your first reviews. Five genuine reviews with 4+ stars will move your plugin noticeably in WordPress.org search. Ask the people you built it for, if you had beta testers or early users. Do not ask for reviews from people who have not actually used it.
Monitor your listing. WordPress.org support forums for your plugin are the primary user communication channel. Reply to questions within 48 hours in the first few weeks. One unanswered support thread does not kill a new plugin, but a pattern of no responses within the first month signals to the directory that the plugin may be abandoned, which affects its ranking.
What good month-1 performance looks like
Based on data from plugins tracked by AutomagicWP, here is a realistic benchmark for new plugin launches.
Most new plugins reach between 10 and 50 active installs in month one. This is the base rate for a plugin with no existing audience, no launch announcement, and no featured placement.
Reaching 100 installs in your first 30 days puts you in roughly the top quartile of new launches. That typically requires some combination of an existing audience (newsletter, social following, existing plugin users), a launch announcement somewhere with reach (WP-related newsletters, communities, or your own list), or very strong SEO placement for a search term with real volume.
Above 500 installs in month one is an exceptional launch. That generally means the developer had an existing audience of meaningful size or the plugin was mentioned in a high-traffic publication or newsletter.
These numbers matter because the WordPress.org algorithm rewards install velocity. A plugin that gets 200 installs in its first week signals demand to the directory and ranks better than one that reaches 200 installs over six months. Early installs compound.
From WordPress.org to distribution
WordPress.org handles the basics of update delivery: when you push a new tag, sites running your plugin see the update notification. For most free plugins, that is sufficient.
But some scenarios are not well covered by the wp.org update model.
If you have a premium version of your plugin, the paid version cannot live on WordPress.org. You need a separate update delivery mechanism for it. Managing that separately from your free version's release workflow creates operational friction.
If you want a beta channel (a way to push pre-release versions to users who opt in without pushing to everyone), WordPress.org has no native mechanism for it.
If you run an agency and your client's site uses a plugin that exists in multiple customized forks across sites, WordPress.org cannot track or distribute those.
This is where AutomagicWP works alongside WordPress.org rather than instead of it. You can keep your free plugin on the directory and use AutomagicWP for premium versions, beta channels, or private agency variants. The update delivery is identical from the WordPress dashboard's perspective; the distribution layer is different. We cover the setup for that in detail in Ship WordPress Plugin Updates Without ZIP Files.
The data side is also worth noting. AutomagicWP's plugin directory at /plugins/ tracks install trends, health scores, and month-over-month data for WordPress.org plugins. After your plugin has been live for a few weeks, you can check its trajectory there alongside the plugins in your category.
Frequently asked questions
How long does the WordPress.org plugin review take in 2026?
Based on new plugin first-appearance data tracked by AutomagicWP, the typical review window is 2 to 4 weeks. Small, focused plugins can move considerably faster: Selektable cleared in four days with 350+ plugins in the queue at the time. Queue length varies by time of year and submission volume. Submitting a clean plugin that matches the guidelines on the first attempt is the single biggest factor in shortening that wait.
What are the most common reasons a plugin gets rejected?
Missing license headers, direct database queries without $wpdb, enqueueing scripts without version parameters, missing nonces on forms, and unescaped output. Reviewers also reject plugins with names that imply an official affiliation with WordPress or WooCommerce when there is none.
Do I need SVN to submit to WordPress.org?
SVN is required to push releases after approval. The initial submission uses a web form at wordpress.org/plugins/developers/add/. After approval you get an SVN repository and every version update goes through it. You do not need deep SVN experience; the commands are a handful of lines and the workflow becomes routine quickly.
What should go in the readme.txt stable tag?
The Stable tag must match the exact version folder you create under /tags/ in your SVN repository. For a plugin at version 1.0.0, your SVN should have a /tags/1.0.0/ folder and your readme should say Stable tag: 1.0.0. Setting it to trunk is documented as an option but the review team discourages it.
What is a good install velocity for a new plugin in the first 30 days?
Based on AutomagicWP data, reaching 100 installs in your first 30 days puts you in roughly the top quartile of new launches. Most new plugins reach 10 to 50 installs in month one without an existing audience or launch push. Above 500 installs in month one is an exceptional result.
Can I use GitHub with a WordPress.org plugin?
Yes. Most teams keep the plugin in Git and use SVN only as a deployment step. 10up's action-wordpress-plugin-deploy GitHub Action automates the SVN commit when you push a release tag. Your development workflow does not change; SVN becomes a one-way deployment target.
Can I use AutomagicWP even if my plugin is on WordPress.org?
Yes. AutomagicWP works alongside the directory. Common use cases are premium versions of a free plugin, beta channels for opted-in users, or agency forks of a public plugin. WordPress.org and AutomagicWP can both be delivering updates to different segments of your user base at the same time.
What is the Tested up to header and why does it matter?
The Tested up to header in readme.txt tells WordPress core and directory search which version of WordPress you have tested against. It affects the compatibility indicator users see in their dashboards and is a ranking signal on WordPress.org. Keep it current. Test against the current stable WordPress release before each plugin update and bump the header accordingly.