How to write a great README

Sections of a great README:


Explain in 1-2 sentences what your project does and why someone should care.

There’s a direct correlation between how easy it is to use the project and how many people are using it, so provide a quickstart demo:


Badges provide metadata and signals that can help someone decide whether to use your project or not. Include info like:

  • Build
  • Code coverage
  • Dependencies
  • Size
  • Downloads
  • Social (e.g., GitHub stars)
  • Version
  • Activity (e.g., last commit)

See Badgen,, and Naereen/badges.


Bring up prerequisites before a user installs the project. If a CLI or binary is required, provide a link to the download page.


Describe the steps to install your project. If your project can be installed with a package manager, add a code block with the install command. If your project has additional build steps, cover them and explain edge cases for specific platforms or operating systems.


Explain how to run the project. This is a good place to describe what each script, class, function, or option does. Additional examples may be beneficial.


Provide instructions on how to release, publish, and deploy the project. Note whether the process is manual or automated and how versioning works.


Provide instructions on how to contact the project maintainer if a security vulnerability is found. This is important because if your project is open sourced, creating an issue will bring awareness to the bug, which puts more pressure on getting a fix out. See adding a security policy to your repository.


It’s good practice to state the project license in the README.


  • helps users understand how to contribute and make changes to your project (see template).
  • [] helps users understand how to conduct interactions with the project (see GitHub Docs).
  • If there are a lot of headings, include a table of contents at the beginning.
  • “3 tips to be a better writer”

Please support this site and join our Discord!