How to make PyPi description Markdown work?

As stated in Martijn Pieters’ answer, PyPi does not support Markdown.

Instead, convert the Markdown files into RestructuredText and upload those to PyPi.

One way to do this is to install Pandoc and PyPandoc, and then arrange to run them during packaging.

On OS X, Pandoc can be installed using Homebrew (brew install pandoc). Use pip (pip install pypandoc) to install PyPandoc.

Then, modify setup.py like so:

try:
    import pypandoc
    long_description = pypandoc.convert_file('README.md', 'rst')
except(IOError, ImportError):
    long_description = open('README.md').read()

setup(
    name='blah',
    version=find_version('blah.py'),
    description='Short description',
    long_description=long_description,
)

I’ve had issues with r characters causing parsing issues where only the first line of the README appears in pypi. The code below fixes the issue, it comes from the pypandoc module repository:

try:
    long_description = pypandoc.convert('README.md', 'rst')
    long_description = long_description.replace("r","") # Do not forget this line
except OSError:
    print("Pandoc not found. Long_description conversion failure.")
    import io
    # pandoc is not installed, fallback to using raw contents
    with io.open('README.md', encoding="utf-8") as f:
        long_description = f.read()

This way long_description contains a sanitized version of your Readme and you can pass it to the setup() function in your setup.py script.

PyPI supports rst and not markdown as mentioned on other answers. But you don’t need pypandoc perse, just pandoc is fine. You can generate the rst file locally first and then run setup.py to upload the package.

upload.sh:

#!/bin/bash
pandoc --from=markdown --to=rst --output=README README.md
python setup.py sdist upload

The generated file named README will be automatically recognized. Be sure to add it to your .gitignore! The setup.py doesn’t have to do anything special.

setup.py:

from distutils.core import setup

setup(
    name='mypackage',
    packages=['mypackage'],  # this must be the same as the name above
    version='0.2.8',
    description='short',
    author='Chiel ten Brinke',
    author_email='<email>',
    url='<github url>',  # use the URL to the github repo
    keywords=[],  # arbitrary keywords
    classifiers=[],
)

Then just run bash upload.sh to upload the stuff to PyPI.

There is a good pip package that worked for me

https://pypi.python.org/pypi/restructuredtext_lint/

I’m using it on my setup now:

https://github.com/pablodav/burp_server_reports/blob/master/setup.py

def check_readme(file='README.rst'):
"""
Checks readme rst file, to ensure it will upload to pypi and be formatted correctly.
:param file:
:return:
"""
errors = rst_lint.lint_file(file)
if errors:
    msg = 'There are errors in {}, errors n {}'.format(file, errors[0].message)
    raise SystemExit(msg)
else:
    msg = 'No errors in {}'.format(file)
print(msg)

Also I have created a lib to be able to use in py.test later

https://github.com/pablodav/burp_server_reports/blob/master/burp_reports/lib/check_readme.py

You can set markdown in setup.cfg file too:

[metadata]
...
long_description = file: README.md
long_description_content_type = text/markdown

Checkout my project as an example: on github and on pypi.

I found the other answers here sort of complicated, and old. I am new to all this, so I’m going to give an answer that uses tools I understand, and worked on my first try.

To get my github page readme.md file to show on my PyPi page, I followed the following two steps in my setup.py file.

1. Include the following at the top of my setup.py file

from pathlib import Path
this_directory = Path(__file__).parent
long_description = (this_directory / "readme.md").read_text()

These steps directly read in the data from your markdown file into the long_description variable.

2. Input the following parameters to the setup() function

long_description = long_description
long_description_content_type="text/markdown"

This inserts the data from your markdown file into long_description, and then tells setup() what type of data it is (markdown).

As I said, the above two steps worked great on my first try, without any hassles or complexity. Perfect for my little brain. 🙂

Note this code is adapted from:
https://packaging.python.org/guides/making-a-pypi-friendly-readme/

2023 Update:

No need for a setup.py file.
Under your poetry.toml file or simply your .toml file, there is a [tool.poetry] section, under that you put readme = "README.md". Example:

[tool.poetry]
name = "Example Module"
version = "0.1.0"
description = "Module Description"
readme = "README.md"
authors = ["Author Name <[email protected]>"]