Project guides

GitHub README template for an open source project

A useful GitHub README answers four questions quickly: what does this project do, who is it for, how do I try it, and where do I get help? Use the Markdown template below as a starting point, then replace every placeholder with information you have checked against your project.

GitHubStart editorial team · Updated

Copy this Markdown README template

This is an authored starter template, not a working software example. Replace bracketed text, check that the referenced files exist, and remove sections that do not apply. The install and run lines below are comments so they cannot accidentally execute placeholder commands.

# [Project name]

[One sentence: the problem, the intended user and the result.]

## Example
[Show one small input and its expected output, or add a screenshot.]

## Quick start
Requirements: [runtime/version and required services].

```sh
# Replace with your verified installation command.
# Replace with the smallest command that produces a useful result.
```

Expected result: [what the reader should see].

## Configuration
[Required settings, safe example values and where to store secrets.]

## When to use this
- [A concrete use case]
- [A second use case]

## Limitations
[Unsupported inputs, maturity, performance or platform constraints.]

## Documentation and help
[Link to documentation and explain where to ask a question.]

## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
Report a reproducible problem through the repository's Issues tab.

## License
See [LICENSE](LICENSE).

Adapt the example to the type of repository

For a command-line tool, show an input file, the command and a short output. For a library, show the smallest complete import-and-call example, including the expected return value. For a web application, show the main workflow and explain whether a hosted demo or local setup is available.

Avoid a screenshot as the only explanation of an API: readers should be able to copy the code. Conversely, a visual application can benefit from a screenshot with a clear description of what the user is doing. Use actual examples from the version you currently distribute.

  • Library: installation, supported runtime and one complete function call.
  • CLI: input, command, output and how errors are reported.
  • Web app: demo link or local setup, configuration and a main-task screenshot.
  • Dataset: provenance, format, license and a small sample record.

Check the README before sharing it

Try the quick start in a clean environment rather than a machine already configured for development. Check whether an undeclared global package, private registry or local file is required. If setup needs an account or paid service, say so before the first command.

Open documentation and image links from the repository page. Confirm that the contribution and license filenames match your repository, and remove broken links. A short accurate README is better than an impressive-looking template full of promises you have not implemented.

  • Remove placeholders and unsupported claims.
  • Keep real tokens, passwords and private URLs out of examples.
  • Check that the expected output matches the published version.
  • Tell readers what to include when they report an issue.

Use the README as your launch brief

After completing the template, extract a short introduction: one sentence about the problem, one example of the result and one link to try it. That becomes the starting point for a community post. Keep the original README as the detailed source, and adapt each introduction to the reader rather than repeating a promotional paragraph everywhere.

Common questions

Is this a repository README or a profile README?

This template is for a software repository. A profile README introduces a person and needs different sections, such as their work and contact preferences.

Should I add Star badges at the top?

Only if they help the reader. Keep the purpose and quick start prominent. A badge is not a replacement for explaining what the project does.

Can I use this template for a private project?

Yes. Replace public support links with your team’s actual help channels, explain access requirements and keep credentials out of the document.

References