Beginner's Guide for WordPress / Start your WordPress Blog in minutes

How to Add Your Plugin to the WordPress Plugin Directory

Would you like 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.

In this article, we will discuss the benefits of adding your plugin to the WordPress Plugin Directory along with 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, and give you greater credibility as a developer.

You won’t have to pay for the bandwidth required to download your plugin, and the directory will 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 mustn’t 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 to make sure you have followed 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.

Creating 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 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: 5.5
Tested up to: 5.8
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’ll need to customize the file for your own plugin, so we’ll 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’ll 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 pluginname’ and Windows users can select ‘Send to » Compressed (zipped) folder’.

Creating Zip File of Your Plugin Folder

Submitting 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 login button at the top right corner of the screen.

Login to WordPress.org

Once logged in, you’ll 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 click on the Upload button.

Upload Your WordPress Plugin for Review

The WordPress.org plugin review team will then take a look at your plugin code for common errors and security checks. Once approved, you’ll 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.

Uploading 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’ll 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 checkout button to continue.

The Versions app will now create the folders needed for your plugin on your computer. You can view it under 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 into 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’ve made major changes to your plugin, you’ll 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.

Adding Artwork to the WordPress Plugin Directory

MonsterInsights Plugin Page

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’ll 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’ll 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 them 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’ll need to click on the Add button to add new assets file into 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 learn the right way to create an email newsletter, or check out our pick of must have plugins that WordPress users find helpful.

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.

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

13 CommentsLeave a Reply

  1. 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.

  2. 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!

  3. 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!

  4. 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

    • I simply left the license line out of the readme file… WP will then assume your plugin is licensed under the default GPLv2 license, which is fine in most cases.

  5. 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.

  6. @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.

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

  8. 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 to Parth Cancel 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.