Use Markdown document on brand new PyPI

Yesterday, PyPI was renewed to the next-generation site. It is modern and stylish one.

@aodag told me that PEP 566, which was accepted Feb. 2018, allows us for a document on PyPI to use not only reStructuredText but also other formats such as Markdown.

So I enabled my Markdown document on brand-new PyPI.

Upgrade Python packages (if necessary)

We can use Markdown with setuptools as of v.38.6.0. Let’s upgrade you python packages if needed. Without that, Markdown description will not be rendered appropriately.

$ python -m pip install –upgrade pip
$ pip install –upgrade wheel
$ pip –version
pip 10.0.0 from c:\users\chezo\documents\source\tabula-py\venv\lib\site-packages\pip (python 3.6)
$ pip list
Package Version Location
-—————- ———– ————————————–
setuptools 38.1.0
wheel 0.31.0


If you’ve already used as a long description on PyPI, all you have to do is to add long_description_content_type to as follows:


You can see the full description of the PR :

Handle markdown long description for Pypi by chezou · Pull Request #85 · chezou/tabula-py
_Thanks for PEP 566, as of setuptools v38.6.0, PyPI can render long description written in markdown. This PR allows…

Build a wheel and upload with twine

Now, you can build a wheel and upload with twine.

$ python bdist_wheel  
$ twine upload dist/*

The Markdown document was rendered!
The Markdown document was rendered!
The Markdown document was rendered!

CAVEAT: I didn’t upgrade PyPI because it is too much to bump up for just rendering Markdown. I tested on


Aki Ariga
Aki Ariga
Staff Software Engineer

Interested in Machine Learning, ML Ops, and Data driven business. If you like my blog post, I’m glad if you can buy me a tea 😉

  Gift a cup of Tea