Dustin Ingram



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_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

Only https://pypi.org will correctly render your new Markdown description.

Legacy PyPI (http://pypi.python.org/) will still render your description as plaintext, but don’t worry, it’s going away real soon. 😉


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, Ernest W. Durbin III 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: