Skip to content

Commit 217512f

Browse files
authored
Merge pull request #2192 from rgommers/image-in-readme-on-pypi
Document how to display README images on PyPI
2 parents 6c48da8 + 635cb43 commit 217512f

1 file changed

Lines changed: 35 additions & 0 deletions

File tree

‎source/guides/making-a-pypi-friendly-readme.rst‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,41 @@ provide both the file path and content type explicitly:
5656
The referenced README should remain in the project source tree so the build
5757
backend can read it when producing package metadata.
5858

59+
60+
Adding images
61+
-------------
62+
63+
To display an image in your project's description on PyPI, use a publicly
64+
accessible HTTPS URL pointing directly to the image. For an image hosted in a
65+
source repository, use the raw file URL rather than the repository's page for
66+
the file.
67+
68+
.. tab:: Markdown
69+
70+
In :file:`README.md`, use Markdown image syntax:
71+
72+
.. code-block:: markdown
73+
74+
![Screenshot of the application](https://example.com/screenshot.png)
75+
76+
.. tab:: reStructuredText
77+
78+
In :file:`README.rst`, use the reStructuredText ``image`` directive:
79+
80+
.. code-block:: rst
81+
82+
.. image:: https://example.com/screenshot.png
83+
:alt: Screenshot of the application
84+
85+
Relative paths such as ``docs/screenshot.png`` may work on your repository's
86+
website, but will not work on PyPI. PyPI does not serve image files from your
87+
uploaded source distribution or wheel for use in the project description.
88+
89+
The same approach works for logos, badges, and animated GIFs. ``data:`` URLs and
90+
embedded video players are not supported; link to externally hosted videos
91+
instead.
92+
93+
5994
Validating reStructuredText markup
6095
----------------------------------
6196

0 commit comments

Comments
 (0)