Developer · Guide
How to Submit and Update a Plugin on WordPress.org

Short answer
To submit a plugin to WordPress.org, create a WordPress.org account, write a valid readme.txt, and upload a zip of the plugin on the Add Your Plugin page. After a manual review approves it, you get a Subversion repo. To update, bump the version in the main file and the Stable tag in the readme, copy trunk to a new tag folder, and commit.
Key takeaways
- A plugin must be GPL version 2 or later compatible and must use the Subversion repo it is given.
- Submission is a zip upload followed by a manual review, and approval brings a Subversion repo.
- The readme short description must stay under 150 characters with no markup.
- The Stable tag in trunk/readme.txt picks which tag folder users download.
- Tags are frozen releases, so every fix ships as a new tag with a higher version number.
What does WordPress.org check before it lists a plugin?
WordPress.org checks that the plugin is GPL compatible, follows the directory guidelines, and is uploaded through its Subversion repo before it appears in the directory.
Your plugin must be compatible with the GNU General Public License version 2, or any later version. WordPress.org lists that rule first among the limits on what the directory will host (checked November 2026).
You must also use the Subversion repo the directory gives you. WordPress.org states that the plugin directory is a hosting site, not a listing site, and that the plugin must actually use the repo to show up (checked November 2026).
The review team reads the code by hand and checks it against the directory guidelines. Developer.WordPress.org hosts the full guideline list, which covers code quality, security, and what a plugin may not do (checked November 2026).
A guide on how many plugins are on WordPress.org gives a sense of the size of the directory your plugin will join.
What do you need before you submit?
You need a WordPress.org account, a finished plugin with a valid header, a readme.txt file, and a name that no other plugin already uses.
Create a WordPress.org account first, because the submission and the SVN repo both use that login. WordPress.org states that the first step is to sign up for an account on WordPress.org (checked November 2026).
Search the directory for your plugin name before you submit. A name that is already taken will be rejected, and a name that is close to a known plugin will confuse users.
Check the plugin header in the main PHP file. Only the Plugin Name field is required, but the directory reads the version and the required WordPress and PHP versions from that file too.
A guide on how to create a WordPress plugin covers the header fields and the folder layout the directory expects.
How do you write a readme.txt that passes?
Write a readme.txt with a header block, a short description under 150 characters, and sections for the description, install steps, and questions.
The readme file builds your public plugin page. Developer.WordPress.org states that the readme controls what shows on the front-facing part of the directory, and that the short description should stay under 150 characters with no markup (checked November 2026).
Start with this header shape:
=== My Plugin ===
Contributors: your-username
Tags: tag1, tag2
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
A short line that says what the plugin does.
The Contributors line holds WordPress.org usernames, separated by commas, and the names are case sensitive. Developer.WordPress.org states that Tags holds 1 to 5 comma-separated terms that describe the plugin (checked November 2026).
| Header field | What it states |
|---|---|
| Contributors | WordPress.org usernames of the authors |
| Tags | 1 to 5 terms that describe the plugin |
| Requires at least | Lowest WordPress version the plugin needs |
| Tested up to | Latest WordPress version checked against the plugin |
| Requires PHP | Lowest PHP version the plugin needs |
| Stable tag | The plugin version users should get |
| License | The GPL-compatible license used |
| Short description | One line under 150 characters, no markup |
Since WordPress 5.8, readme files are no longer parsed for requirements. Developer.WordPress.org states that the Requires PHP and Requires at least headers are now read from the main PHP file instead (checked November 2026).
Put the finished readme through the official readme validator before you submit. Developer.WordPress.org states that you can use the plugin readme generator and check the result with the official validator (checked November 2026).
How do you submit the plugin for review?
Zip the plugin folder, upload it on the Add Your Plugin page, and wait for the review team to reply.
Submission has four steps. WordPress.org states that you sign up for an account, submit the plugin for review, wait for the manual review, and then get access to a Subversion repo once approved (checked November 2026).
Upload the zip at the plugin developer pages. The submission form lives at wordpress.org/plugins/developers/add/, where you attach the zip and send it for review (checked November 2026).
After the upload, the team runs an automated scan and a human reads the code. If the code needs fixes, the team emails you with the list of changes to make, and you reply with a fixed zip.
Do not upload the plugin to the SVN repo before approval. The repo does not exist until the review passes, and only approved plugins get one.
How does the review work?
A reviewer reads your code against the directory guidelines, then approves the plugin or emails you a list of fixes to make.
Every plugin submitted is fully reviewed by the plugin review team. WordPress.org states that after the manual review, the plugin will either be approved or you will be emailed and asked to provide more details or make corrections (checked November 2026).
Common reasons for a fix request are a missing readme, a name that clashes with another plugin, and code that does not follow the guidelines. Read the guideline list before you submit, not after the first rejection.
Fix each item in the email, then reply with a new zip. The review picks up where it left off, so a clear reply with a list of what changed speeds the next pass.
Once approved, you get access to a Subversion repo where you will store the plugin. WordPress.org states that shortly after you upload the plugin and a readme file to that repo, it will show in the plugin browser (checked November 2026).
How do you upload the first version with SVN?
Check out the repo, put the code in trunk, add the assets, tag the release, and commit.
Subversion, or SVN, is a version control system like Git. Developer.WordPress.org states that the repo has three folders by default: assets, tags, and trunk (checked November 2026).
| Folder | What goes in it | Shipped to users |
|---|---|---|
| trunk/ | Current development code and the readme | Only if the Stable tag says trunk |
| tags/ | One frozen folder per released version | Yes, the one the Stable tag names |
| assets/ | Screenshots, header images, and icons | No, used for the listing page only |
Check out the repo with your WordPress.org username, which is case sensitive. Developer.WordPress.org states that your SVN account is the same username, not the email, that you used to submit the plugin (checked November 2026).
svn co https://plugins.svn.wordpress.org/my-plugin my-plugin
Copy your plugin files into trunk, with the main PHP file and readme.txt at the top level of trunk. Developer.WordPress.org states that you must not put the main plugin file in a subfolder of trunk, because that breaks downloads (checked November 2026).
Add the files, copy trunk to a tag folder, and commit:
svn add trunk/* --force
svn cp trunk tags/1.0.0
svn ci -m 'First release 1.0.0'
SVN and the directory form a release repo, not a place to develop. Developer.WordPress.org states that you should only push finished changes, because committing every small change can hurt performance (checked November 2026).
How do you release an update?
Bump the version in the main plugin file, update the Stable tag in the readme, copy trunk to a new tag folder, and commit.
First, change the Version line in the main plugin file header and the Stable tag line in trunk/readme.txt to the same new number, such as 1.1.0. The two values must agree, or the directory page will show the wrong version.
The directory reads the Stable tag from trunk/readme.txt first. Developer.WordPress.org states that when the Stable tag is set, WordPress.org looks in the tags folder for that version, and reads all other details from the readme in that tag (checked November 2026).
If the Stable tag is missing or set to trunk, the version in trunk is treated as stable. Make WordPress states that a Stable tag of 1.2.3 makes the directory look in tags/1.2.3, and that a change to the trunk readme alone will not show on the page (checked November 2026).
Copy the trunk code to the new tag and commit:
svn cp trunk tags/1.1.0
svn ci -m 'Release 1.1.0'
Update the Tested up to line in the readme each time you check the plugin against a new WordPress release, even when the code did not change. A stale Tested up to value warns users that the plugin may not work with their WordPress version.
After the commit, check the plugin page and confirm the version number and the changelog show the new release. Users get the update through the normal WordPress update screen.
How do you fix a rejected or broken release?
Fix the fault in trunk, tag a new version with a higher number, and commit, because a tag folder must never change after release.
Never edit a tag folder after users have it. Tags are frozen copies of a release, and the only fully supported way to ship a fix is a new tag with a higher version number.
If the fault is in the readme only, edit the readme in trunk and in the current tag, then commit. Make WordPress states that the version users see comes from the main PHP file, so keep that Version line in step with the tag (checked November 2026).
If the directory closed the plugin, read the email from the review team first. A closed plugin stays closed until the listed faults are fixed and the team confirms the fix.
A guide on how to check a plugin for vulnerabilities covers the security checks to run before you tag a fix, so the new release does not repeat the fault.
How do you handle the plugin assets?
Put banner images, icons, and screenshots in the assets folder at the top of the repo, never inside trunk.
The assets folder holds the images for the listing page. Developer.WordPress.org states that you use assets for screenshots, plugin headers, and plugin icons (checked November 2026).
Screenshot files in assets match the numbered screenshot captions in the readme. A caption that names screenshot 1 pairs with the first screenshot file, so keep the numbers in step when you add or remove images.
Add the assets with the same commit as the release, or in their own commit before it:
svn add assets/* --force
svn ci -m 'Add listing images'
Keep the images small and in a web format such as PNG. Large images slow the listing page and add weight to every checkout of the repo.
What mistakes should you avoid?
Avoid a name clash, a readme that does not match the code, and a release that skips the tag step.
A name that is already taken wastes a full review cycle. Search the directory first, and pick a name that is clearly yours.
A readme that names a Stable tag with no matching tag folder leaves users on the trunk code, which may be unfinished. Create the tag folder before you commit the readme change.
Skipping the tag step and setting the Stable tag to trunk ships unfinished code to users. Tag each release, and keep trunk for work in progress.
Forgetting the license blocks approval. The plugin must be GPL version 2 or later compatible, and the license line must appear in both the readme and the main file header. GNU.org hosts the full text of the GPL version 2 license (checked November 2026).
A guide on how to remove unused plugins and themes safely covers the user side of the directory.
A guide on are nulled WordPress plugins safe explains why users should only install plugins from the directory.
Frequently asked questions
Can I submit a plugin with any license?
No. The plugin must be compatible with the GNU General Public License version 2 or later. The directory will not host a plugin with a license that blocks sharing, and the license line must appear in the readme and the main file.
What happens if my plugin is rejected in review?
The team emails you a list of fixes to make. Fix each item, reply with a new zip, and the review picks up where it left off. Read the guideline list before you resubmit.
Can I edit a tag folder after release?
No. Tags are frozen copies of a release. Fix the fault in trunk, tag a new version with a higher number, and commit that tag instead.
How does WordPress.org pick which version to serve?
The Stable tag in trunk/readme.txt picks the tag folder, such as tags/1.2.3. If the tag is missing or set to trunk, the code in trunk is treated as stable, so always create the tag folder first.
Do I need a new version number for every update?
Yes. Set the Stable tag to the new version, copy trunk to tags/1.1.0, and commit. If you only need to update the Tested up to line, edit the readme in trunk and in the current tag and commit.
Sources
- Developer Information WordPress.org
- Using Subversion WordPress Developer Resources
- Plugin Readmes WordPress Developer Resources
- Detailed Plugin Guidelines WordPress Developer Resources
- The Plugins directory and readme.txt files Make WordPress
- GNU General Public License v2.0 GNU.org
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


