A good README answers four questions fast: what is this, why should I care, how do I install it, and how do I use it. The best README examples put those answers in the first screen, then layer in badges, screenshots, and contribution rules below. This post breaks down eight real READMEs from well-known projects, shows what to copy from each, and gives you a template you can paste into a new repo today.
If you are still mapping out how your project should be explained, our guide on how to document code covers the wider picture, and our roundup of code documentation tools helps once a single file stops being enough. For the README itself, keep reading.
What a great README actually contains
A README is the front door of a repository. It is the first file GitHub, GitLab, and Bitbucket render on the project page, so it sets the first impression before anyone reads a line of code. The file is almost always written in Markdown and named README.md in the top-level directory.
The strongest READMEs share a predictable shape. A reader should be able to scan top to bottom and never feel lost. Here is the anatomy that shows up across nearly every good README example.
| Section | Purpose | Skip it when |
|---|---|---|
| Title + one-line description | Says what the project is in plain words | Never |
| Badges | Build status, version, license, coverage | Tiny personal scripts |
| Install | The exact commands to get it running | Never for a tool |
| Usage / quick start | Smallest working example with output | Never for a library |
| Features | What sets it apart from alternatives | Obvious utilities |
| Screenshots / GIF | Visual proof for UI or CLI projects | Pure backend libraries |
| Configuration | Options, flags, environment variables | Zero-config tools |
| Contributing | How to submit changes and run tests | Closed personal projects |
| License | Legal terms for reuse | Never for public repos |
You do not need every row. A 40-line Python utility and a framework like React have different needs. The rule is simple: include the sections a stranger needs to use your project without asking you a question.
8 README examples worth copying
These are real READMEs from projects you likely already know. Each one does something specific well. I have noted the single thing worth stealing from each.
1. Standard Readme (RichardLitt/standard-readme)
This repo defines a README specification, so its own README is a reference example. It opens with a clear title, a badge, and a one-sentence description, then uses a table of contents because the file is long. The section order is consistent and documented.
Steal this: the table of contents. Once a README passes roughly 150 lines, a TOC built from anchor links saves readers from endless scrolling.
2. Create React App (facebook/create-react-app)
The README leads with what the tool does and a single command to get started. It does not bury the quick start under philosophy. New users hit a working command within seconds of landing on the page.
Steal this: the install-first ordering. Put the one command that proves the project works above everything optional.
3. Prettier (prettier/prettier)
Prettier opens with a punchy description, an animated GIF showing the formatter in action, and a list of supported languages. The visual does more work than three paragraphs of prose could.
Steal this: a GIF or screenshot near the top. For anything with visible output, show it before you describe it.
4. Poetry (python-poetry/poetry)
Poetry keeps its README short and points to a dedicated documentation site for depth. The README handles intro, install, and a quick example, then links out. It resists the urge to document every flag inline.
Steal this: the restraint. A README should orient, not exhaust. Long reference material belongs on a docs site, not in README.md.
5. Awesome README (matiassingers/awesome-readme)
This is a curated list of great READMEs, and the list format is the example. It groups links under clear headings and stays scannable across hundreds of entries.
Steal this: heading discipline. Even a long list reads fast when every section has a meaningful H2 or H3 and entries follow the same pattern.
6. Express (expressjs/express)
Express shows a minimal working server in about ten lines right after the install command. A reader sees the smallest possible program that does something useful before any API detail.
Steal this: the minimal viable example. Show the smallest snippet that returns real output, then link to fuller examples.
7. Black (psf/black)
Black, the Python formatter, opens with its tagline ("The uncompromising code formatter"), a row of badges, and a short pitch on why uncompromising is the point. The personality is intentional and memorable.
Steal this: a tagline with a point of view. A confident one-liner is more memorable than a generic "a tool for formatting code."
8. The Algorithms (TheAlgorithms/Python)
A large community project, its README uses badges, a clear contributing section, and links to a community chat. It treats the README as an on-ramp for contributors, not just users.
Steal this: a real contributing path. If you want help, spell out exactly how to submit a change and where to ask questions.
A copy-paste README template
Start here and delete the sections you do not need. This is plain Markdown, so it renders correctly on GitHub, GitLab, and inside most editors.
# Project Name
One sentence that says what this project does and who it is for.
## Features
- The main thing it does
- The second thing it does
- What makes it different from alternatives
## Installation
npm install project-name
## Usage
import { doThing } from "project-name";
const result = doThing("input");
// => "expected output"
## Configuration
| Option | Default | Description |
|----------|---------|------------------------------|
| apiKey | none | Your API key for the service |
| timeout | 5000 | Request timeout in ms |
## Contributing
Pull requests are welcome. For major changes, open an issue first to
discuss what you would like to change. Run the test suite before submitting:
npm test
## License
[MIT](LICENSE)
A few rules that keep this template effective:
- Put the description and the one command that proves it works above the fold.
- Use a real usage snippet with a comment showing the expected output.
- Keep configuration in a table so options stay scannable as they grow.
- Link to a
LICENSEfile rather than pasting the full legal text inline.
What separates a good README from a forgettable one
The difference is rarely length. It is ordering and proof. A forgettable README opens with backstory and a wall of installation caveats. A strong one opens with what the project is, shows it working, and only then gets into detail.
Three habits show up in almost every great README example:
- Show, then tell. A code block or a GIF beats a paragraph describing behavior.
- Write for a stranger. Assume the reader has never met you and has thirty seconds.
- Link out instead of dumping. Deep reference material goes to a docs site, with the README pointing the way.
If you want more on the writing side, our piece on how to write documentation covers tone and structure, and for code-heavy projects, JavaScript documentation gets specific about documenting functions and APIs.
When your README outgrows itself
A README is a starting point, not the whole story. The moment you find yourself adding a sixth <details> block, a fourth nested heading, or a "see the wiki" link buried at the bottom, the file is doing too much. That is the signal to move detail into a real docs site.
When your README is doing too much, tools like Docsio generate a full branded documentation site from your existing content in minutes. You paste a repo URL or your existing Markdown, and AI documentation generation turns it into a structured, searchable site. Your README then shrinks back to its job: orient the reader, then point to the docs. If you are working from a longer outline, a technical documentation template gives you a starting structure for the full site.
Frequently asked questions
What is a README file example?
A README file example is a real README.md from a project that you can study and copy. Strong examples include create-react-app, Prettier, and Express. Each opens with a one-line description, an install command, and a short usage snippet, then adds badges, screenshots, and contributing rules below.
How do I write a README?
Write it as a plain Markdown file named README.md in your project root. Start with a one-sentence description, add an install command, show a small usage example with expected output, then list features, configuration, and license. Order it so a stranger can use the project without asking you anything.
What should I write in a README?
At minimum: the project name, a one-line description, installation steps, and a usage example. Add badges, a features list, screenshots or a GIF for visual projects, configuration options, contributing guidelines, and the license as your project grows. Include only the sections a new user actually needs.
What is a README used for?
A README introduces and explains a project to anyone who finds it. Code hosting platforms render it on the project page, so it acts as the front door. It answers what the project is, how to install it, how to use it, and how to contribute, all before someone reads the source code.
What does a good README look like?
A good README opens with a clear title and one-line description, proves the project works with an install command and a short example, then layers in features, visuals, and contributing details. It is scannable, written for a stranger, and links out to a docs site instead of dumping every detail inline.