Key takeaways from this article:
- Low installs after launch is the normal starting point for almost every plugin — not a verdict on the plugin’s quality. The WordPress.org algorithm doesn’t permanently punish new plugins for low early traction.
- WordPress.org search runs on a two-phase algorithm. Phase one matches keywords in your readme. A readme rewrite can change your rankings within days — not months.
- The most common cause of low installs is a fixable readme problem, not a product problem. The title and short description carry the most algorithmic weight and are almost always under-optimized on stalled plugins.
- Six months at 10 installs is completely recoverable. Developers routinely see meaningful movement within a week of making targeted readme changes.
- The same plugin, optimized readme, can go from invisible to ranking on page one for relevant searches. The algorithm rewards the work — and the work takes an afternoon, not a rebuild.
Your plugin has been live for six months and the install count is stuck at ten. Before you start second-guessing the idea, questioning the code, or wondering whether to abandon it — take a breath. This is one of the most common situations in WordPress plugin development, and it has a well-understood cause that has nothing to do with plugin quality.
Almost every plugin starts here. About 79% of plugins in the WordPress.org directory never get past 100 installs — not because they’re bad, but because discoverability on WordPress.org is a skill that most developers never learn. The good news: it’s a learnable skill, the fix is fast, and the algorithm responds quickly once you make the right changes.
Let’s walk through what’s actually happening and what to do about it today.
The Real Reason Installs Are Low
The WordPress.org plugin directory has over 59,000 free plugins. When a developer needs a solution, they type a few words into the search bar and get a list. If your plugin doesn’t appear in that list for the searches your target users are running, it doesn’t get installed — regardless of how well it’s built.
This isn’t a reflection on the plugin. It’s a discoverability problem, and discoverability on WordPress.org is controlled almost entirely by what’s in your readme.txt file. The algorithm doesn’t evaluate code quality, user experience, or feature depth. It evaluates specific fields in your readme and ranks based on how well those fields match what users are searching for.
Most developers — even experienced ones — focus their energy on building the plugin and treat the readme as an afterthought. That’s completely understandable. It’s also why most plugins start slow. The readme is the marketing layer that makes the algorithm work for you, and it’s fixable in an afternoon.
How the Algorithm Actually Works
Understanding the two phases of WordPress.org search makes the fix obvious.
Phase one — keyword matching. The algorithm searches your readme for the exact words and phrases in the user’s query. It checks your title, short description, long description, tags, slug, and contributor names. If the user searches for “automatic image optimizer” and those words don’t appear together in your readme, your plugin is excluded from results — full stop. Install count doesn’t matter at this stage. A brand new plugin with zero installs beats a five-year-old plugin with thousands of installs if the new plugin’s readme matches the query and the old one doesn’t.
Phase two — quality ranking. Among plugins that passed phase one, the algorithm ranks by signals including active install count, average rating, last update date, WordPress version compatibility, and percentage of resolved support tickets. This is where established plugins have an advantage — but it’s an advantage that erodes as your installs grow.
Here’s the encouraging part: most stalled plugins are failing at phase one. They’re simply not appearing in results because the readme doesn’t contain the phrases users are searching. Fix phase one and new installs start arriving. New installs gradually improve your phase two signals. The flywheel starts turning on its own.
Unlike Google, where meaningful ranking changes can take weeks or months, WordPress.org rankings respond quickly to readme changes. Developers routinely see movement within one to three days of making targeted updates. You’re not waiting for a long-term SEO campaign to play out — you’re making a change and watching the results almost immediately.
Four Common Patterns — All Fixable
Most stalled plugins have one or more of these issues. All of them are straightforward to address once you know what to look for.
Wrong Keywords
Your readme uses the language you use to describe the plugin — not the language users type when they need it. This is the most common issue and the easiest to fix once you know what your users actually search for.
Brand-Name Title
“Acme Plugin” as your title tells the algorithm nothing about what you do. The title carries the most algorithmic weight of any field. Moving your keyword phrase to the front takes two minutes and makes an immediate difference.
Generic Short Description
The short description is the second most important field and is almost always wasted on vague copy like “the ultimate solution for your needs.” It needs your exact target phrase. One sentence rewrite.
Single-Word Targets
“Backup.” “Security.” “SEO.” These are dominated by plugins with massive install counts. Two and three-word phrases are where new plugins can compete right now — and there are plenty of them available.
The One Change That Moves the Needle Fastest
If you do nothing else today, rewrite your title. It’s the single highest-impact change available and it takes about two minutes.
Most plugin titles look like this: “Acme Image Plugin — Image Optimization for WordPress.” Brand name first, keyword phrase buried. The algorithm weights the first words in the title heavily for exact phrase matching.
Rewrite it like this: “Automatic Image Optimizer — Acme.” Now the exact phrase a user searches for is at the front. Brand comes after. You haven’t changed a line of code. You’ve just made the plugin findable by the people who need it.
After the title, update your short description — 150 characters, contains your primary keyword phrase, describes what the plugin actually does. Not a tagline. A description. “Automatically compresses and resizes images on upload, with no quality loss and no manual steps” is infinitely more useful to the algorithm than “The smartest image plugin you’ll ever install.”
Finding the Right Keywords
Rewriting your title and short description only works if you’re targeting phrases people actually search. The question is: what are those phrases, and which ones are your competitors already winning?
This is where the diagnostic work pays off. You want to know which keywords your plugin currently ranks for, which keywords your competitors rank for that your readme doesn’t mention, and which of those gaps are worth targeting.
The manual version — searching term by term, noting positions, comparing readmes — takes hours and goes stale quickly. WhoKnew Directory SEO™ automates the entire process. It tracks your live keyword positions on WordPress.org, surfaces every term your competitors rank for that you’re missing, scores your readme field coverage across all seven fields the algorithm indexes, and generates an AI-ready optimization prompt pre-loaded with your gaps and competitor benchmarks. Download the free version from WordPress.org and run the competitor gap analysis before you change anything — it tells you exactly what to write instead of guessing.
The Full Recovery Checklist
Here’s the complete sequence, in order of impact. You can realistically work through most of this in an afternoon:
- 1
Run competitor analysis first. Identify the keyword gaps between your plugin and the top three competitors in your category. These are your targets. Don’t optimize blind.
- 2
Rewrite your title. Keyword phrase first, brand name at the end. Highest-impact single change. Do this today.
- 3
Rewrite your short description. 150 characters, contains your primary keyword phrase, describes what the plugin does for the user. One sentence.
- 4
Expand your long description with gap keywords. Incorporate the phrases from your competitor analysis naturally through the description, FAQ, and changelog. The algorithm needs to find these phrases in your readme.
- 5
Get at least one genuine review. A plugin with zero reviews gets treated as 2.5 stars by the algorithm — which actively hurts your phase two ranking. Reach out to anyone who tested your plugin and ask for an honest review. One review changes the calculation immediately.
- 6
Resolve all open support tickets. The algorithm tracks resolved ticket percentage. If you have any open ones, close them now.
- 7
Update “Tested up to.” Make sure your readme reflects the current WordPress version. An outdated compatibility header is an unnecessary penalty.
- 8
Track your positions after changes. WordPress.org doesn’t show you where you rank for specific keywords. Use a tracking tool to watch movement — you should see changes within one to three days.
Ranking movement typically shows within one to three days of readme changes on WordPress.org. New installs from improved rankings follow shortly after. The install count itself builds gradually — more installs improve your phase two ranking, which generates more installs. The flywheel is slow to start but self-sustaining once it does. Most developers who go through this process see meaningful movement within the first week. The plugin you built is already good enough. It just needs to be findable.
Further Reading
- How WordPress.org Search Works and What It Means for You — a deep dive into the two-phase algorithm that decides who gets found.
- The 7 Fields WordPress.org Actually Indexes — which fields carry the most weight and how to optimize each one.
- How to Spy on Any Competitor’s WordPress.org Plugin Keyword Strategy — find the exact keywords your competitors rank for before you rewrite your readme.
- How to Rank Your Plugin on WordPress.org — the complete ranking guide from first principles.
- Why Your Plugin Is Buried on Page 8 (And the 10-Minute Fix) — the quick-win version for developers who need movement fast.
Who knew the plugin you spent three months building could start moving in three days — just by changing the words in the readme file.
