使用numpy.distutils.setup打包至PyPI时README.md无法正常渲染求助

我之前也碰到过一模一样的困扰——用numpy.distutils.core.setup打包时，PyPI上的README总是没法正确渲染成Markdown格式，换成setuptools的setup就一切正常。核心原因是numpy.distutils的setup函数默认不会告诉PyPI你的长描述是Markdown类型，而setuptools会自动处理这个细节。下面是几个可行的解决办法：

1. 手动指定long_description_content_type参数 #

这是最直接的修复方式，你只需要在config字典里添加一行，明确告知PyPI你的长描述是Markdown格式：

config = {
    'name':'CrystalTorture',
    'version':__version__,
    'description':'A Crystal Tortuosity Module',
    'long_description': long_description,
    # 新增这一行，指定内容格式为Markdown
    'long_description_content_type': 'text/markdown',
    'url':'https://github.com/connorourke/crystaltorture',
    'python_requires':'>=3.5',
    'packages':['crystal_torture'],
    'package_dir':{'crystal_torture':'crystal_torture'},
    'package_data':{'crystal_torture':['*so','*tort*','*dist*','*o*']},
    'include_package_data':True,
    'license': 'MIT',
    'install_requires': ['ddt', 'coverage', 'f90wrap', 'numpy', 'pymatgen' ]
}

PyPI必须依赖这个参数才能识别长描述的格式，没有它的话，哪怕你传入了标准Markdown内容，也会被当成纯文本展示。

2. 确保README文件读取时使用正确编码 #

有时候文件读取的编码问题也会导致渲染异常，建议你打开README.md时明确指定utf-8编码：

with open(os.path.join(this_directory, 'README.md'), encoding='utf-8') as f:
    long_description = f.read()

这能避免因系统默认编码差异导致的字符乱码，进而影响PyPI的渲染效果。

3. 升级numpy到较新版本 #

旧版本的numpy.distutils可能不完全支持long_description_content_type参数，建议你确保numpy版本在1.19.0以上，这个版本之后numpy.distutils对PyPI打包的兼容性有明显提升。

额外验证小技巧 #

打包前可以用twine check dist/*命令检查你的包是否存在问题，它会直接提示你长描述的格式是否被正确识别，这样就能提前发现问题，不用等到上传到Test PyPI才看到渲染异常。

内容的提问来源于stack exchange，提问作者abinitio