This template gives you those sections in order, with placeholders you replace. It works for GitHub, GitLab, Bitbucket, and any repository host that renders Markdown.
Need it as a document? Paste the filled-in template into the free Markdown to Word or Markdown to PDF converter.
README key facts
- Name the file
README.mdso repository hosts render it as Markdown. - GitHub shows a README from the
.githubdirectory, the repository root, or thedocsdirectory, checked in that order. - State what the project does in the first sentence, before badges, history, or credits.
- Give a copy-paste install command and the smallest working usage example.
- Use relative links (for example
docs/setup.md) so links work on every branch and in local clones. - On GitHub, content beyond 500 KiB in a README is truncated, so move long reference material into separate docs.
- Link to
CONTRIBUTING.md,LICENSE, andSECURITY.mdinstead of repeating them.
Copyable Markdown README template
# [Project name]
[One sentence that says what the project does and who it is for.]
[](#) [](LICENSE)
## Table of contents
- [About](#about)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Running tests](#running-tests)
- [Roadmap](#roadmap)
- [Getting help](#getting-help)
- [Contributing](#contributing)
- [License](#license)
- [Maintainers](#maintainers)
## About
[Explain the problem the project solves and why it is useful. Two or three short paragraphs are enough. Link to longer documentation instead of repeating it here.]
![Screenshot of [Project name]](docs/images/screenshot.png)
## Features
- [Feature and the benefit it provides]
- [Feature and the benefit it provides]
- [Feature and the benefit it provides]
## Requirements
- [Runtime or language and minimum version]
- [Operating system support]
- [External service, database, or tool]
## Installation
```bash
git clone https://github.com/[owner]/[repository].git
cd [repository]
[install command]
```
## Usage
[Show the smallest example that produces a visible result.]
```bash
[command or code example]
```
Expected output:
```text
[What the user should see]
```
## Configuration
| Setting | Default | Description |
|---|---|---|
| `[SETTING_NAME]` | `[default]` | [What it controls] |
## Running tests
```bash
[test command]
```
## Roadmap
- [ ] [Planned item]
- [ ] [Planned item]
See the [open issues](https://github.com/[owner]/[repository]/issues) for the full list.
## Getting help
- **Documentation:** [Link]
- **Questions:** [Discussions, forum, or chat link]
- **Bug reports:** [Issue tracker link]
- **Security issues:** See [SECURITY.md](SECURITY.md). Do not report vulnerabilities in public issues.
## Contributing
Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request. Notable changes are recorded in [CHANGELOG.md](CHANGELOG.md).
## License
Distributed under the [License name] license. See [LICENSE](LICENSE) for details.
## Maintainers
- [Name] ([@handle](https://github.com/[handle]))
## Acknowledgments
- [Project, person, or resource that helped]
What a good README answers
A reader arriving from a search result, a package registry, or a link in a chat usually wants to decide one thing quickly: is this the project I need? Answer that in the title and the first sentence. Then answer the next questions in the order people ask them:
- What does it do? One sentence, then a short About section.
- Why is it useful? The problem it solves or the features that matter.
- How do I start? Requirements, installation, and a first working example.
- Where do I get help? Documentation, discussions, and the issue tracker.
- Who maintains it, and can I contribute? Maintainers, the contributing guide, and the license.
If a section does not apply, delete it. An empty Roadmap or a Configuration table with one placeholder row is less useful than no section.
Writing the installation and usage sections
Write installation steps as commands a reader can paste into a terminal. State the minimum supported version of the runtime or language, because "requires Node" or "requires Python" without a version leads to avoidable issues.
The usage example should be the smallest input that produces a visible result. Show the expected output under it so readers can confirm the install worked. Put advanced options, API references, and tutorials in separate documentation pages and link to them.
Test every command in a clean environment before publishing. A README with a broken first command loses readers at the point where they were ready to use the project.
Links, images, and navigation
Use relative links for files inside the repository, such as [setup guide](docs/setup.md) or . GitHub adjusts relative links to the branch being viewed, and they keep working when someone clones the repository.
GitHub also builds a table of contents from your headings (the Outline button on the rendered file) and gives each heading an anchor you can link to. A manual table of contents, as in the template, is still useful on hosts and editors that do not generate one. Keep heading text stable, because changing a heading changes its anchor and breaks links to it.
Add alt text to images and keep screenshots current. A screenshot of an old interface is misleading.
README generator or template?
A README generator asks questions and fills in a file for you. A template does the same job with less setup: copy it, delete what you do not need, and replace the placeholders. Either way, the content that matters (what the project does, the real install command, a working example) has to come from you. Review a generated README against the checklist in the table below before committing it.
For a longer walkthrough of each section, see the guide on how to write a README.
Completed README example
# csvtidy
csvtidy cleans messy CSV files from the command line: it trims whitespace,
normalizes headers, and removes empty rows.
## Requirements
- Python 3.10 or later
## Installation
pip install csvtidy
## Usage
csvtidy input.csv --out clean.csv
Expected output:
Cleaned 1,204 rows. Removed 18 empty rows. Wrote clean.csv.
## Getting help
Open an issue at https://github.com/example/csvtidy/issues.
## Contributing
See CONTRIBUTING.md.
## License
MIT. See LICENSE.
This example is short but complete. The first sentence says what the tool does, the requirements name a version, and the usage section shows a command with the output a reader should expect. The project name and URL are fictional.
What to include in a README
| Section | What to write |
|---|---|
| Title and one-line description | Project name and what it does, in one sentence |
| About | The problem it solves and who it is for |
| Requirements | Runtimes, versions, operating systems, and services |
| Installation | Copy-paste commands from a clean starting state |
| Usage | Smallest working example and its expected output |
| Configuration | Settings, defaults, and environment variables |
| Getting help | Documentation, discussions, issue tracker, security contact |
| Contributing | Link to CONTRIBUTING.md |
| License | License name and link to the LICENSE file |
| Maintainers | Names or handles of the people responsible |
README FAQ
Where should README.md go in a GitHub repository?
Put it in the repository root in most cases. GitHub also recognizes a README in the hidden .github directory or the docs directory. If more than one exists, GitHub shows the one in .github first, then the root, then docs.
How long should a README be?
Long enough to answer what the project does, how to install it, how to use it, and where to get help. Move detailed reference material into separate documentation. On GitHub, content beyond 500 KiB is truncated.
Should a README include a table of contents?
It helps when the README has more than five or six sections. GitHub generates an outline from headings automatically, but a manual list of links also works on other hosts and in local editors.
What is the difference between a README and documentation?
A README is the entry point: it orients a new reader and gets them to a first working result. Documentation covers full reference, tutorials, and edge cases. Link from the README to the documentation.
How do I make a GitHub profile README?
Create a public repository with the same name as your GitHub username and add a README.md to its root. GitHub shows that file on your profile page.
Related templates
- CONTRIBUTING.md template
- CHANGELOG.md template
- Technical design document template
- Architecture decision record template
- How to write a README (guide)
- All Markdown templates