Markdown Descriptions on PyPI

Dustin Ingram

Writing — Speaking — GitHub — Social

Finally! #

I’m really excited to say that as of today, PyPI supports rendering project descriptions from Markdown! This has been a oft-requested feature and after lots of work (including the creation of PEP 566) it is now possible, without translating Markdown to rST or any other hacks!

For example, this markdown-description-example project has a Markdown description, take a look at the source here.

Here are the steps necessary to make a new release with a Markdown description of your project:

1. Have a `README.md` #

And make sure it contains markdown. The extension doesn’t have to be .md (.mkdn or .markdown or anything else is fine), just be sure you’re reading it in and setting it as the long_description.

2. Add a new argument in `setup.py`: #

PEP 566 added new metadata fields including Description-Content-Type. To set the content type for your long description, you’ll need to add the following argument to the setup() call in your projects setup.py:

    long_description=long_description,
+   long_description_content_type="text/markdown",

3. Upgrade your `setuptools`: #

You’ll need a version of setuptools>=38.6.0 to be able to produce a distribution with the new metadata.

$ pip install -U setuptools

You also must be actually using setuptools. This means that in your setup.py you have an import like:

from setuptools import setup

4. Make a source distribution #

This is the same as usual:

$ python setup.py sdist

You may see a warning from distutils which can be safely ignored:

Unknown distribution option: 'long_description_content_type'

Note: If you’d like to create a wheel as well, perhaps with python setup.py bdist_wheel, you will need a version of wheel>=0.31.0:

$ pip install -U wheel

5. Upgrade your `twine`: #

You must upload the distribution with twine, and only twine>=1.11.0 will correctly send the metadata to PyPI:

$ pip install -U twine

6. Upload the distribution: #

This is also the same as usual:

$ twine upload dist/*

7. View your project on `pypi.org` #

Visiting your project page on https://pypi.org to see your new Markdown description.

Thanks #

Thanks to Marc Abramowitz for originally starting the push for this feature, to Nick Coghlan and Daniel Holth for help and guidance with PEP authorship and reviews, to Tres Seaver, Sumana Harihareswara and Jason R. Coombs for reviewing, testing and releasing pull requests, and the entire PyPI team including Nicole Harris, Ee Durbin and Donald Stufft for being amazing teammates.

Follow me #

If you want to stay up to date with all the latest PyPI changes, you can follow me: