Write a high-quality README for NuGet packages

UPDATE (July 1, 2026): This post was updated to refresh our recommendations for a high-quality README. See the updated sections below.

Based on our recent customer interviews and surveys, one of the top problems that package consumers face is insufficient package documentation, such as README, changelog, examples, and API reference. On the other hand, package authors may struggle with best practices for creating a clear and concise README. Our goal is to improve the overall experience for both consumers and authors by addressing this issue.

The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. It’s also one of the first things users will see when they view your package on NuGet.org. Therefore, it’s essential for package authors to write a high-quality README.

– Image from MySqlConnector package

High quality READMEs are not limited to a specific format or structure. Instead, it’s about effectively communicating the purpose and functionality of your package to potential users. For this guidance, we would like to share our perspectives on how to write a high-quality README and provide support for package authors who may be unsure about best practices of creating a README. By following our tips and best practices, we hope you can improve the quality of your READMEs and better serve your users.

What may a high-quality README include

We recommend organizing your README around the following sections. Each maps directly to a question your consumers are asking as they scan the page:

• Start with a clear and concise description of what your package is and does, and what problem it solves. This is the first thing users read, so keep it focused and jargon-light.
• Call out the highlights of your package as a short bulleted list. This helps users quickly decide whether the package fits their scenario without reading the full doc.
• Help users become productive quickly: note any installation prerequisites or setup, then walk through real examples covering the scenarios users most commonly need.
• Identify the few public types users will interact with most, so they know where to begin rather than searching the full namespace.
• List links such as detailed documentation, tutorial videos, blog posts, or any other relevant documentation to help users get the most out of your package.
• If your package is part of a family or works alongside others, list companion packages here so users can find the rest of the ecosystem.
• Tell users where and how to leave feedback and how to contribute. Include your license, a link to your GitHub repository (or other bug tracker), and any contribution guidance.

README template

Here is a template to get you started with writing a great README for your package.

# Package readme title, e.g., display name or title of the package (optional)

## About
A brief overview of what your package is and does, and what problem it solves. Keep this to a short paragraph so users can grasp the value at a glance.

## Key Features
- Highlight the key capabilities of your package.
- Keep each one short and outcome-focused.

## How to Use
Explain how to install and use your package, including any prerequisites or setup steps. Then provide concrete code snippets that demonstrate the most common scenarios.

## Main Types
The main types provided by this library are:
- `Your.Namespace.PrimaryType`
- `Your.Namespace.SecondaryType`
- `Your.Namespace.HelperType`

## Additional Documentation
- Conceptual documentation
- API documentation
- Tutorials, samples, or blog posts

## Related Packages
- `Your.Related.Package.One` - brief description of how it relates.
- `Your.Related.Package.Two` - brief description of how it relates.

## Feedback & Contributing
Tell users how your package is licensed, where to report bugs, and how to contribute.

Examples of high-quality READMEs

As we mentioned earlier, well-written READMEs can come in a wide variety of styles, shapes, and sizes. Here are packages on NuGet.org we found that are well-written and incorporated some best practices:

• System.Text.Json
• Azure.Storage.Blobs
• MySqlConnector
• System.IO.Abstractions

Other good practices

• API reference: If applicable, link to the package’s API documentation.
• Badges: If applicable, provide code coverage, build status, code quality and so on (NuGet.org supports badges and images from a trusted allow-list of domains, feel free to file an issue if you think another domain should be added to the allow-list, we will review it for security and privacy compliance).
• Table of contents: A README should contain necessary information for package consumers to get started using and where and how to leave feedback. If your README is long with all necessary information, a table of contents may help users navigate the README more easily. You could add links to a section within your README using markdown syntax like below:

  [Text to sub-heading](#text-of-the-subheading)
  

• Troubleshooting: Provide information on how to troubleshoot common issues that users may encounter when using the package.

Additional documentation

• If you are new to NuGet README, learn more about how to add a README to your NuGet Package.
• A list of Markdown features NuGet.org supports.

We want to hear your feedback

Show us your best package README on Twitter with #nugetreadme and we’ll highlight the winners in a future blog!

Your feedback is very important to us. If you experience any issue using READMEs or have ideas for improvements – please feel free to contact us by filing an issue.

For more general NuGet feedback and suggestions:

• Check out our documentation on submitting bugs and suggestions.
• Schedule a time to talk to NuGet.
• Reach out to us on Twitter – mention @nuget in your tweets.