How to get your first users for an open-source project
8 min read
You shipped something that works. You use it yourself. And months later the user count is still zero, or close to it. This is the most common and most demoralising stage of an open-source project, and almost everyone misreads it as a promotion problem.
It usually is not. First users do not come from announcing. They come from two things: being useful in the places where your users already have the problem, and having a repository that converts the attention you earn. Announcing, the thing everyone reaches for first, is the lowest-yield channel there is, which is exactly why posting "I built this" to ten communities so reliably returns nothing.
Here is the order that actually works.
First, get specific about who your first users are
"Developers" is not an audience. If the most precise thing you can say about who your project is for is "developers" or "teams," you cannot go where your users are, because you have not decided who they are.
Name the two or three specific people who have the exact problem your project solves. Not "people who write Python," but "people wiring an LLM into a CI pipeline who need the build to fail when output quality drops." The sharper that sentence, the more obvious the next steps become: you now know which threads to answer, which communities to be in, and what the first line of your README has to say.
Most projects skip this step and then wonder why their scattershot posting goes nowhere. Scattershot posting is that missing sentence showing up as a symptom.
Fix the thing that loses them in thirty seconds
Before you send anyone to your repository, make sure the repository does not lose them the moment they arrive. Your README is your landing page, and developers give a README seconds, not minutes, before deciding whether to keep reading or close the tab.
The first screen has to answer three questions fast: what is this, who is it for, and what does it look like working. A runnable example and a one-line install beat three paragraphs of philosophy. The most common README mistake is explaining every feature before showing a single useful result. Reverse that order: show value, then explain.
This is not a soft opinion. We graded more than 2,000 public READMEs to work out what actually separates the ones on adopted projects from the rest, and the pattern is consistent: the opening, a visible example, and a fast path to first use matter more than completeness. We wrote up the ten-second version of that test in what a README has to do in ten seconds, and you can grade your own README for free, no sign-up, in a few seconds.
Why fix this before promoting? Because if the repository converts badly, more traffic just means more bounces. Driving people to a page that loses them is worse than driving nobody, because you have spent the one impression each of them will give you.
Go where your users already have the problem
Now, the part everyone gets backwards. The goal is not to announce your project in as many places as possible. It is to be genuinely useful in the two or three places where your specific users already discuss the problem, so that your project comes up as the answer to a real question rather than as a broadcast.
A reply that solves someone's exact problem, with your project mentioned because it is genuinely the best answer, converts. A post that says "check out my thing" does not, and on most developer communities it is removed. Pick two or three venues where your users actually are, not ten, and show up as a participant before you show up as a publisher. We keep a running list of where to post an open-source project, with each community's self-promotion rules, because posting to the wrong place in the wrong way is the fastest way to burn a channel.
Show HN works for the right project because its audience is there specifically to find new tools. Language and framework communities work because the problem is already on-topic. General startup and "rate my project" rooms mostly do not, because the people in them are not your users.
Your first ten users come from reaching out, one at a time
This does not scale, and that is fine, because you do not need it to scale at ten. Find the specific people who have just described the problem you solve, in an issue, a thread, a post, and show them your project. Not a pitch, a demonstration: here is the thing, here is how it handles exactly what you were struggling with.
Ten real users who chose to try it after a human conversation will teach you more, and stick around longer, than a thousand drive-by stars. The first ten are hand-made. Later growth can be systematic.
Ship releases with real changelogs
Every release is an honest, recurring reason to appear again: a changelog, a short note about what changed and why it matters. It is the one kind of "look at my project" post that communities tolerate, because it carries news rather than just a link.
One caveat, because we measured it: a release mostly buys a one-day spike. When we tracked six weeks of one maintainer's promotion against their actual download data, downloads jumped on release days and were gone within a day. So treat releases as a steady cadence that keeps you visible, not as a growth engine on their own. The compounding comes from the useful-in-context work above; releases keep the lights on between.
Stop counting stars, start counting the five who left
Stars are the most available number and one of the least informative. A repository with 800 stars and no activity in six months has fewer real users than a 60-star project that ships weekly and answers issues within a day. Chasing stars optimises for a vanity metric that does not pay rent.
The highest-signal research you can do costs nothing: find five people who looked at your project and did not use it, and ask them why. Five honest answers will tell you more than any amount of theorising about whether your problem is reach, your README, or the product itself, which is the question most maintainers never actually resolve.
How to tell what is actually wrong
"Nobody is using it" is three different problems wearing one coat, and the fix for each is different. You can tell them apart by where people drop off.
| What you observe | The real problem | What to do |
|---|---|---|
| Almost nobody reaches the repository at all | Reach | Be useful where your users already have the problem; do not just announce |
| People reach it and leave in seconds (views, no stars or installs) | Conversion | Fix the README and the positioning; the repo is losing them |
| People try it and do not come back | Product | Ask the ones who left; it is features, trust, or fit, not promotion |
Most maintainers assume it is reach and pour a month into posting, when the repository is quietly converting badly and more traffic cannot help. Spend an hour deciding which of the three you actually have before you spend a month on the wrong one. This reach-versus-conversion split is the whole reason we built Orviqa to read a repository and name what is limiting its adoption instead of guessing.
The one-week version
If you only have a week:
- Write the one sentence that says who your two or three first users are.
- Rewrite the first screen of your README to answer what-it-is, who-for, and show one runnable example. Grade it.
- Pick two communities where those users already discuss the problem. Answer three real questions there, no links.
- Message five specific people who described your problem, and show them the project.
- Ship a release with a real changelog.
None of this is announcing. All of it is being useful where your users are, to a project that does not lose them when they arrive. That is how the first users actually come.
Orviqa reads your repository and tells you who it is for, what is most limiting its adoption, and which communities those users are already in, with a draft for each. Nothing is posted without your approval. If you would rather just see where your README stands first, the README grader is free and needs no account.