Trusted WordPress tutorials, when you need them most.
Beginner’s Guide to WordPress
WPB Cup
25 Million+
Websites using our plugins
16+
Years of WordPress experience
3000+
WordPress tutorials
by experts

How to Add Your Plugin to the WordPress Plugin Directory

Editorial Note: We earn a commission from partner links on WPBeginner. Commissions do not affect our editors' opinions or evaluations. Learn more about Editorial Process.

Do you want to add a plugin you created to the WordPress plugin directory?

Contributing useful plugins to the directory is just one of the ways you can give back to the WordPress community. But you may need some pointers on how to add your plugin to the official plugin directory.

In this article, we will show you a step-by-step guide on how to add your plugin to the repository.

How to Add Your Plugin to the WordPress Plugin Directory

Why Add Your Plugin to the WordPress Plugin Directory?

If you have created a WordPress plugin that you think would be useful to others, then you should consider adding it to the official WordPress plugin directory. This has lots of benefits for you as a developer.

The WordPress plugin directory is the first place many users go when looking for plugins for their WordPress website. Adding your plugin to the directory will make it easier for users to find it and give you greater credibility as a developer.

Plus, you won’t have to pay for the bandwidth required to download your plugin. The directory will also automatically keep track of how many people have downloaded it and will notify them when there is an upgrade.

The directory will also help you support the plugin. Users can rate your plugin, leave feedback and bug reports, and make use of the support forum.

AIOSEO Plugin Support Forum

Of course, there are also some requirements and restrictions. The first is that your plugin must have a license that’s compatible with WordPress. GPLv2 or later is recommended.

There are also some ethical considerations to keep in mind. The plugin must not do anything illegal or morally offensive, and you can’t include links to external websites without first getting the users’ permission.

After you submit the plugin, it will be manually reviewed for common errors and compliance with the plugin directory guidelines. That process can take between 1 and 10 days.

With that being said, let’s have a look at how to add your plugin to the WordPress plugin directory step by step. You can use the quick links below to navigate through this article:

Step 1: Create a readme.txt File for Your Plugin

The first thing you need to do is create a ‘Read Me’ file for your plugin. This will be displayed on your plugin’s page in the plugin directory and needs to use the right formatting.

Here is a sample file you can use as a starting point. You will need to paste it into your text editor and save the file as readme.txt in your plugin folder:

=== Your Plugin Name ===

Contributors: Your WordPress.org Username
Tags: wpbeginner, plugin tutorial
Requires at least: 6.0
Tested up to: 6.2
Stable tag: 1.0
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

A WordPress plugin to teach beginners how to write a WordPress plugin. 

== Description ==

This simple plugin is part of our beginner's guide to writing a WordPress plugin. 

== Installation ==

1. Upload the plugin folder to your /wp-content/plugins/ folder.
1. Go to the **Plugins** page and activate the plugin.

== Frequently Asked Questions ==

= How do I use this plugin? =

Answer to the question

= How to uninstall the plugin? =

Simply deactivate and delete the plugin. 

== Screenshots ==
1. Description of the first screenshot.
1. Description of the second screenshot. 

== Changelog ==
= 1.0 =
* Plugin released.

You will need to customize the file for your own plugin, so we will explain how the WordPress plugin readme file syntax works.

The first line is the ‘Plugin Name’ and will appear in the WordPress plugin directory as your plugin’s title.

The next line is ‘Contributors.’ These are the WordPress.org user IDs responsible for managing your plugin. If you don’t already have a user ID, then you will need to create a free WordPress.org user account.

The ‘Requires at least’ and ‘Tested up to’ fields refer to the WordPress versions your plugin works with. The ‘Stable tag’ is the version of your own plugin.

You can leave the License fields the same. Then, you should edit the ‘Description’ area to explain what your plugin does.

After editing your plugin’s readme file, don’t forget to save your changes. It’s also a good idea to run the file through the official Readme Validator and address any issues that are identified.

Finally, you should right-click on your plugin folder and create a zip file. Mac users should select ‘Compress [plugin name],’ and Windows users can select ‘Send to » Compressed (zipped) folder.’

Creating Zip File of Your Plugin Folder

Step 2: Submit Your Plugin to the Directory for Review

Now, your plugin is ready to be reviewed by WordPress.org’s plugins team.

To submit it, visit the Add Your Plugin page. If you are not already logged in, then click on the ‘Log in’ button in the top right corner of the screen.

Logging in to WordPress before adding a new plugin

Once logged in, you will be able to upload and submit your plugin for review.

Simply click on the ‘Select File’ button to select your plugin’s zip file. And then, check all of the boxes that apply and click on the ‘Upload’ button.

Submitting a plugin to WordPress

The WordPress.org plugin review team will then take a look at your plugin code for common errors and security checks. Once approved, you will receive an email from the plugins team.

This email will contain a link to the Subversion (SVN) repository where your plugin will be hosted on WordPress.org. You will need to use this link when you upload your plugin.

Step 3: Upload Your Plugin Using Subversion (SVN)

Once your plugin is approved, you will need to use Subversion (SVN) to upload the plugin.

Subversion is an open-source version control system. It allows users to make changes to files and directories while keeping a record of changes, managing different versions, and collaborating with other users.

You will need an SVN client installed on your computer to upload your plugin. Windows users can use SilkSVN or TortoiseSVN (free). Mac users can install SmartSVN or the Versions app on their computers.

In this article, we will use the Versions app for Mac. However, the process is very similar in all the SVN apps listed above.

Once installed, you need to open the Versions app and check out a copy of your WordPress plugin’s repository. To do that, simply click on the ‘New Repository Bookmark’ button.

New Repository Bookmark

This will bring up a popup where first, you need to provide a name for this bookmark. You can name it after your plugin. After that, you need to add your WordPress plugin’s SVN repository URL.

You can leave the username and password fields blank.

Connect Your Repository

Now, you should click the ‘Create’ button. Versions will connect with your repository and download a copy of your plugin’s repository to your computer.

Next, you need to right-click on the repository name in the browser view and then select ‘Checkout’.

Check out your repository

You will be asked to provide a name for the folder and select a location where you want to store it on your computer. You can use the same folder name as your plugin directory and click on the ‘Checkout’ button to continue.

The Versions app will now create the folders needed for your plugin on your computer. You can view it in your plugin’s repository or browse it in Finder.

Show Local Repository in Finder

Now, you need to copy your plugin files and paste them inside the trunk folder of your local repository.

As you do that, you will notice a question mark icon next to new files in the Versions app.

Since these files didn’t exist before, you need to add them. Select the new files and click on the ‘Add’ button to add these files to your local folder.

Add Files

Now that your plugin files are added to Subversion, you are ready to upload them. You do this by syncing changes in your local folder and the subversion directory.

You should click on your local repository to select it and then click on the ‘Commit’ icon.

Commit Changes

A new popup will appear, and you will see the list of changes and a box to add a commit message.

Once you click the ‘Commit’ button, the Versions app will sync your changes and commit them to your plugin’s repository.

Adding a Commit Message

Now that you have uploaded your plugin files to the trunk, it’s time to tag them to a version.

Go to the local copy of your plugin and copy the files inside the trunk folder. After that, you need to open the tags folder and create a new folder inside it.

Name this folder with a version name. Make sure that it matches the version you have entered in your plugin’s header. In the sample code above, we have used version 1.0 for our plugin.

After adding the 1.0 folder, you need to paste your plugin files inside. Since this is a new folder, you will also need to click on the ‘Add’ button to include the folder and all its files in the repository.

Add Files

After that, you can go ahead and click on the ‘Commit’ icon to sync your changes as you did earlier. You can now visit the WordPress plugins directory and preview your plugin.

Whenever you need to edit your plugin files, you should edit the local copy. Once you are done with your changes, simply click on the ‘Commit’ icon to sync them with the WordPress plugin directory.

When you have made major changes to your plugin, you will want to add a new version by adding a new folder with that version number to the tags folder. Make sure that the version number matches your plugin’s header.

Step 4: Add Artwork to the WordPress Plugin Directory

MonsterInsights plugin banner image

Now, we can add some artwork and screenshots to the WordPress plugin directory. These items need to follow standard naming practices and should be uploaded using Subversion.

Plugin Header Banner

The header banner is the large image that appears on top of the plugin page. Its size should be 772×250 or 1544×500 pixels, and you should use the JPEG or PNG file format.

Depending on the size of your image and the file type, you will need to give your header banner one of these names:

  • banner-772×250.jpg
  • banner-772×250.png
  • banner-1544×500.jpg
  • banner-1544×500.png

Plugin Icon

The icon is a smaller square image and will be displayed in search results and plugin listings. Its size should be 125×125 or 250×250 pixels, and you should use the JPEG or PNG file format.

Depending on the size of your image and the file type, you will need to give your icon one of these names:

  • icon-128×128.jpg
  • icon-128×128.png
  • icon-256×256.jpg
  • icon-256×256.png

Screenshots

You can add as many screenshots as you like. These screenshots should be listed in the screenshot descriptions in your readme.txt file.

Screenshot files should be named like this:

  • screenshot-1.png
  • screenshot-2.png

Once you have prepared all the artwork, you can place it into the assets folder of your plugin’s local copy.

After that, you will notice a question mark icon next to the assets folder. You will need to click on the ‘Add’ button to add new assets files to your repository.

Add Assets

Finally, go ahead and click on the ‘Commit’ icon to upload your files to the WordPress plugin directory.

After a while, you will be able to see the artwork appear on your plugin page.

Commit Changes

We hope this tutorial helped you learn how to add your plugin to the WordPress plugin directory. You may also want to check out our pick of the must-have plugins that WordPress users find helpful and learn how to prevent clients from deactivating WordPress plugins.

If you liked this article, then please subscribe to our YouTube Channel for WordPress video tutorials. You can also find us on Twitter and Facebook.

Disclosure: Our content is reader-supported. This means if you click on some of our links, then we may earn a commission. See how WPBeginner is funded, why it matters, and how you can support us. Here's our editorial process.

Editorial Staff

Editorial Staff at WPBeginner is a team of WordPress experts led by Syed Balkhi with over 16 years of experience in WordPress, Web Hosting, eCommerce, SEO, and Marketing. Started in 2009, WPBeginner is now the largest free WordPress resource site in the industry and is often referred to as the Wikipedia for WordPress.

The Ultimate WordPress Toolkit

Get FREE access to our toolkit - a collection of WordPress related products and resources that every professional should have!

Reader Interactions

14 CommentsLeave a Reply

  1. Syed Balkhi says

    Hey WPBeginner readers,
    Did you know you can win exciting prizes by commenting on WPBeginner?
    Every month, our top blog commenters will win HUGE rewards, including premium WordPress plugin licenses and cash prizes.
    You can get more details about the contest from here.
    Start sharing your thoughts below to stand a chance to win!

  2. Jindo Nguyen says

    Thank you !.
    You helped me solve the issue when uploading my first plugin. Your guide really easier than using the command line.
    This is my new plugin which approval some months ago based on your article.

  3. Mo a says

    What happens after the plugin is uploaded for the first time? How long should I expect to wait before I can find it on WordPress.org and download it directly via the WordPress plugin search?

    Thank you for a great article!

  4. Ralph says

    When trying to upload my plugin files via Tortoise’s SVN Commit option, the commit was blocked because of the following error: “Please provide the commit message that describes the changes you are making.”

    It was easily fixed by entering “First commit.” in the “Message” box (below the “Recent messages” button) of the Commit dialog.

    Thanks for the tutorial!

  5. Parth says

    I have created wordpress plugin

    I want to host it into wordpress.org

    Can anyone let me know what should be the value of license?

    I want to make it free

    What should i write in licese for readme.text file

  6. Keely says

    Wish I could find a SIMPLE tutorial on this – nobody seems to want to explain it REALLY SIMPLY. I hate getting irritated when I’m doing something new.

  7. wpbeginner says

    @mrahmadawais When it is your first time, then you will SVN all folders…. tags, trunk, branches….

    But once that is done, you only need to commit the changes that are needed.

  8. mrahmadawais says

    can someone elaborate me the last step? when we upload through svn ? what should we upload which folder?

  9. jdblundell says

    Thanks for this! I had one dickens of a time trying to upload my plugin (http://casadeblundell.com/jonathan/wordpress/) originally and after I upgraded it last I haven’t been able to post the latest version.

    I’ll have to walk through this and see what I’m missing – although the only real change is that the plugin works with the latest WordPress version.

Leave A Reply

Thanks for choosing to leave a comment. Please keep in mind that all comments are moderated according to our comment policy, and your email address will NOT be published. Please Do NOT use keywords in the name field. Let's have a personal and meaningful conversation.

WPBeginner Assistant
How can I help you?

By chatting, you consent to this chat being stored according to our privacy policy and your email will be added to receive weekly WordPress tutorials from WPBeginner.