Skip to content

Project Descriptions

The short description

The short description is a concise, one-sentence overview of your project. It's often the first thing a potential user will read, appearing in search results and at the top of your PyPI project page.

Best practices for your short description

  • Be brief and to the point: Aim for a single, impactful sentence that encapsulates your package's core purpose
  • Use clear and understandable language: Avoid jargon where possible. Describe what the package does for the user
  • Highlight the key benefit: What is the primary problem your package solves? Make this evident

Specifying the short description

The short description is set via the description field in pyproject.toml. See Writing your pyproject.toml for more information.

The long description

The long description is your opportunity to provide a comprehensive overview of your package. This is where you can elaborate on its features, provide usage examples, and link to relevant resources. A well-structured long description serves as the main documentation on your PyPI page.

The most common and recommended practice is to use the contents of your project's README file as the long description. This approach keeps your documentation consistent between different platforms like GitHub and PyPI.

Choosing a markup language

PyPI supports several markup languages for rendering the long description. The most popular choices are:

  • Markdown: A lightweight and easy-to-read markup language. GitHub Flavored Markdown is the default
  • reStructuredText (rST): A powerful markup language often used in the Python ecosystem, particularly for documentation generated by Sphinx
  • Plain Text: If you prefer no special formatting

Specifying the long description

The long description is set via the readme field in pyproject.toml. See Writing your pyproject.toml for more information. PyPI infers the markup language from your readme file's extension — for example, readme = "README.md" renders as Markdown, while readme = "README.rst" renders as reStructuredText.

Considerations for long descriptions

  • Keep it updated: Ensure your README accurately reflects the current state of your project
  • Structure for readability: Use headings, lists, and code blocks to make your description easy to scan and understand
  • Include key information: See PyOpenSci's excellent guidelines on writing effective READMEs
  • Validate your markup: Before uploading your package, it's a good practice to check if your long description will render correctly on PyPI. You can use twine check to validate your package's metadata and description. You can also use TestPyPI to preview your rendered long description.