How WordPress.org Plugin Search Really Works

Q: Does the plugin name in my PHP file control how the plugin is listed?

No. The directory display title comes from the === Plugin Name === line in readme.txt, not from the Plugin Name: header in the PHP file, and the two can differ. We confirmed this on a live plugin: the slug internal-links returns the API name "Internal Link Juicer: SEO Auto Linker for WordPress" while its PHP header reads simply "Internal Link Juicer". In practice, put the keyword-bearing title in readme.txt and keep the PHP header short, because the PHP header is what users see in their wp-admin plugins list.

Q: Does setting a high "Requires at least" version hide my plugin from search?

No. WordPress core's plugin-install list table calls is_wp_version_compatible() only to disable the Install button and show a notice — the plugin is still listed in the results. So a minimum version set higher than you actually need wastes impressions rather than removing them. For context, wordpress.org's own version statistics at the time of writing showed roughly 19% of WordPress installations running a version older than 6.8.

The WordPress.org plugin directory is a search engine. Millions of installs start there, either on wordpress.org itself or inside the Plugins → Add New screen in wp-admin. And yet most plugin developers spend months on their code and about four minutes on the readme file that decides whether anyone ever finds it.

Here is the part that makes it worth your afternoon: unlike Google, the directory’s rules are readable. The code that parses your readme and the code that builds the search index are public. You can open them, read what they actually do, and then check the result against the live wordpress.org API. No guessing, no “SEO expert says.”

We did exactly that, mostly because we kept getting things wrong ourselves. What follows is four mistakes we either made or watched other authors make, each one tied to a behaviour we verified. We have deliberately left out everything we could not confirm.

Methodology

Everything below was checked two ways:

Reading the directory’s public source. The readme parser and the search code that powers the directory are openly available. Where we make a claim about parsing or weighting, it comes from reading that code, not from inference.
Verifying against the live wordpress.org API. For each behaviour we pulled real plugin records from the public plugins API and confirmed that what the code says should happen is what actually comes back. Where we cite a specific plugin, we pulled its record directly.

Two honesty notes before we go further. We are not affiliated with the WordPress.org plugin directory, the plugins team, or Automattic. And this behaviour can change — the directory is a live system maintained by volunteers and staff, and a commit tomorrow could invalidate any of this. Everything here reflects what we could observe at the time of writing. If you are reading this a year later, re-verify before you act on it.

Mistake 1: a title that contains none of the words people search for

In the directory’s search code, the plugin title and slug carry the heaviest weighting of any field. Tags, the short description and the long description all carry meaningfully less. Author and contributor fields sit somewhere in between.

Read that again, because the implication is blunt: a title that matches no term in the user’s query is a large handicap that no amount of keyword-stuffing further down the readme will make up for. If your plugin is called “Sparklewrench” and someone searches for “contact form,” you are starting the race with a weight on your back.

This is where a lot of authors talk themselves into a bad decision. Brand names feel professional. But the directory does not know your brand, and neither does the person typing three words into a search box at 11pm.

There is a common objection here: surely the trademark guideline stops me putting “WordPress” in the name? Guideline 17’s restriction on trademarks applies to the plugin slug, not the display name. Plugins added as recently as 2025 carry “for WordPress” in their display name, and one live plugin is called Independent Analytics – WordPress Analytics Plugin. So the descriptive-title pattern is not forbidden. Use judgment, do not squat on someone else’s brand, and remember the slug is where the hard rule lives.

Mistake 2: treating tags as a keyword dumping ground

This is the one we personally burned the most time on.

The tag limit is five, and it is enforced in the readme parser itself. The parser runs the equivalent of array_slice( $this->tags, 0, 5 ). Tags six and beyond are not truncated at display time or de-prioritised in ranking — they are never stored, never indexed, never shown, and never reach the API at all. They simply cease to exist the moment your readme is parsed.

We verified this on a live plugin: wp-polls declares ten tags in its readme. The API returns exactly five.

If you have ever written a readme with twelve carefully chosen tags, seven of them were decoration for an audience of one.

It gets slightly worse. The official guidelines list “use of over 5 tags total” as spammy behaviour. So the extra tags do nothing for you and are explicitly named as a thing you should not do.

Given exactly five slots, two more traps are worth knowing about.

Ultra-specific tags waste a slot

A tag used by only a very small number of plugins is treated as low-usage and is not displayed. So the beautifully precise phrase that describes exactly what your plugin does may be doing nothing at all. Our own example: the tag link suggestions is used by just 2 plugins. We had it in a readme. It was a wasted slot, and we only noticed when we went looking.

Competitor names are prohibited

Guideline 12 is explicit, and it is worth quoting in full because people paraphrase it wrongly:

Related products may be used in tags but not competitors. If a plugin is a WooCommerce extension, it may use the tag “woocommerce.” However if the plugin is an alternative to Akismet, it may not use that term as a tag.

The distinction is related versus alternative to. Extending something is fine. Competing with it is not. If you want to make a comparison, make it in the description prose, where it belongs.

Mistake 3: assuming the PHP header drives the listing

This one is genuinely counterintuitive, and we have seen experienced developers get it backwards.

The directory display title comes from the readme’s === Plugin Name === line, not from the Plugin Name: header in your main PHP file. They are two independent strings that most people assume are one.

We verified this by pulling a live plugin. The slug internal-links returns the API name “Internal Link Juicer: SEO Auto Linker for WordPress”, while the Plugin Name: header in its PHP file reads simply “Internal Link Juicer”.

That is not a bug on their part — it is the correct move, and it is the practical takeaway of this whole section. Put the longer, keyword-bearing title in readme.txt, where it feeds the directory’s most heavily weighted field. Keep the PHP header short and human, because that is the string your users stare at every day in their wp-admin plugins list. Nobody wants a search-engine keyword string sitting in their installed-plugins table forever.

Mistake 4: setting `Requires at least` higher than you need

Plenty of authors bump their minimum WordPress version out of caution, on the assumption that incompatible users simply will not see the plugin. That assumption is wrong, and the direction it is wrong in matters.

Requires at least: does not hide your plugin from the in-dashboard plugin search. WordPress core’s plugin-install list table calls is_wp_version_compatible() only to disable the Install button and show a notice. The plugin is still listed. The user still sees your card, still reads your title, and still cannot install you.

So a too-high requirement does not remove impressions — it wastes them. You get the visibility and none of the installs, which is the worst of both outcomes.

How much does this cost? From wordpress.org’s own version statistics at the time of writing, roughly 19% of WordPress installations were running a version older than 6.8. That is your ceiling for the damage if you set a modern minimum without needing to. If your code genuinely requires a recent API, set it and move on. If you set it because it felt tidy, you have quietly disqualified about a fifth of the audience that will still be shown your listing.

The summary table

The mistake	What actually happens	What to do
Brand-only title with no query terms in it	Title and slug carry the heaviest weighting in the directory’s search code; a non-matching title is a large handicap	Get your primary search phrase into the readme title. “For WordPress” and descriptive suffixes are used by live plugins; the trademark rule targets the slug
Listing more than five tags	The parser slices to the first five. Tags 6+ are never stored, indexed, shown, or returned by the API. Over five tags is also listed as spammy behaviour	Pick five deliberately. Verify what the API actually returns for your slug
Using an ultra-specific tag	Very low-usage tags are not displayed — the slot does nothing	Check how many plugins use a tag before spending a slot on it
Tagging a competitor’s name	Guideline 12 permits related products as tags but prohibits competitors	Tag what you extend. Put comparisons in the description prose
Assuming `Plugin Name:` in PHP sets the listing title	The listing title comes from the readme’s `=== Plugin Name ===` line; the two are independent	Keyword-bearing title in readme.txt, short human name in the PHP header
Setting `Requires at least` too high	The plugin is still listed; core only disables the Install button and shows a notice	Set the true minimum. ~19% of installs were below 6.8 at the time of writing

A note on measuring any of this

If you change your readme and then refresh the API every morning hoping to watch installs climb, you will be disappointed. active_installs from the API is bucketed, not exact. It reports 0 until a plugin crosses roughly ten installs, then moves in steps. It is a milestone, not a daily metric.

This is a recurring theme in plugin analytics generally: the numbers you are handed are coarser than they look. We ran into the same thing on the web side, where a large share of what looked like search impressions turned out to be bot traffic distorting the baseline. Treat coarse numbers as coarse and you will make better decisions than someone reading noise as signal.

Limits of this piece

We want to be straight about what this is. It is a careful reading of public code plus verification against the live API. It is not insider knowledge, we have no relationship with the plugins team, and we have not reverse-engineered any ranking formula beyond the relative field weighting that is visible in the source. Where we said “heaviest weighting,” we mean the ordering is legible in the code — we have not published numbers because we would be making them up.

The directory can also change without announcement, and readme parsing has changed before. Re-verify anything here against the API before you rewrite six plugins on our say-so.

And the most important limit of all: none of this beats being a plugin people actually want. Every one of these fixes is worth doing, and together they might be the difference between page one and page three. But they are amplifiers. A well-optimised readme on an unloved plugin gets you a slightly larger audience for your support queue. Discovery buys you the first click; the plugin has to earn the second. The graveyard of the directory is full of well-tagged listings for plugins nobody has maintained in three years.

Fix the readme in an afternoon. Then go back to the code.

Frequently asked questions

How many tags can a WordPress plugin have?

Five. The limit is enforced in the readme parser itself, which slices the tag list to the first five entries, so tags six and beyond are never stored, never indexed, never displayed and never returned by the wordpress.org API. The official guidelines also list use of over five tags total as spammy behaviour. We verified the slicing on a live plugin: wp-polls declares ten tags in its readme and the API returns exactly five.

Does the plugin name in my PHP file control how the plugin is listed?

No. The directory display title comes from the === Plugin Name === line in readme.txt, not from the Plugin Name: header in the PHP file, and the two can differ. We confirmed this on a live plugin: the slug internal-links returns the API name “Internal Link Juicer: SEO Auto Linker for WordPress” while its PHP header reads simply “Internal Link Juicer”. In practice, put the keyword-bearing title in readme.txt and keep the PHP header short, because the PHP header is what users see in their wp-admin plugins list.

Does setting a high “Requires at least” version hide my plugin from search?

No. WordPress core’s plugin-install list table calls is_wp_version_compatible() only to disable the Install button and show a notice — the plugin is still listed in the results. So a minimum version set higher than you actually need wastes impressions rather than removing them. For context, wordpress.org’s own version statistics at the time of writing showed roughly 19% of WordPress installations running a version older than 6.8.