40

In my readme on GitHub I have several images that are present there in my project's source tree which I reference successfully with directives like

.. image:: ./doc/source/_static/figs/moon_probe.png

I would also like to have these images appear when this same readme is generated in PyPi.

How do I (a) ensure that images are present on PyPi for the readme to access and (b) formulate the .. image:: directive to access them?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
orome
  • 45,163
  • 57
  • 202
  • 418

5 Answers5

41

PyPI will not read your package distributions for the image. You have to use the image's external link, for example:

.. image:: https://raw.githubusercontent.com/greyli/flask-share/master/images/demo.png

If you are using Markdown description, use this:

![](https://raw.githubusercontent.com/greyli/flask-share/master/images/demo.png)

Be sure to replace the URL in the above examples with your image URL, here I use the image hosted by GitHub, the real demo is on PyPI.

P.S. To get the image's raw link on GitHub, right-click the image and choose Copy image address.

Grey Li
  • 11,664
  • 4
  • 54
  • 64
  • Doesn't work, requires a token that expires now. I've seen one or two that still work, but they seem to be in markdown rather than RST. – Gringo Suave Mar 16 '20 at 23:24
  • 2
    This is the only thing that worked for me. In markdown, a link would look like this: `![](https://raw.githubusercontent.com/username/project/branch/image.png)` – Mike Conigliaro Mar 22 '20 at 21:27
  • @MikeConigliaro Is it important to use `![](...)` rather than `![alt text](...)`? The latter just displays the alt text on PyPi for me. – stefanbschneider Jan 18 '21 at 14:42
  • Does this also work for gifs? Are they displayed on PyPi? – stefanbschneider Jan 18 '21 at 14:42
  • @CGFoX I'm not sure, but here's where I used it: https://pypi.org/project/smtptester/ – Mike Conigliaro Jan 19 '21 at 16:10
  • works for me in md w the normal github.com url ending w `?raw=true` – Kermit Jan 28 '21 at 21:47
  • @CGFoX no, you can use alt text and it will render fine, that was just an example. You can see for example the [`requests` readme](https://pypi.org/project/requests/) uses an image [with alt text](https://raw.githubusercontent.com/psf/requests/master/README.md). – Boris Verkhovskiy Mar 01 '21 at 17:40
9

Go to the image address in the Github repository. The path shown will be like this: https://github.com/tensorbored/kds/blob/master/docs/_static/readme_lift.png enter image description here Change the blob term in the image address to raw https://github.com/tensorbored/kds/raw/master/docs/_static/readme_lift.png enter image description here

Prateek Sharma
  • 1,371
  • 13
  • 11
  • 3
    I was just going to do this, but if I understand correctly, then ALL PyPi versions, as they age, will continue to pull their images from the `master` branch, meaning things like screenshots might represent a newer version of the codebase than what is *actually* only that PyPi release. It works, but it might be disingenuous. – Evan Rusackas Jan 12 '23 at 21:53
  • 1
    @EvanRusackas You can replace `master`/`main` with a git tag name like `v0.1.0`, and update it at release time. A tool like BumpVer could help like this. – 1j01 Jul 22 '23 at 02:03
4

Setting ?raw=True at the end of GitHub image link seems to work.

example:

![Sample image](https://github.com/usename/reponame/blob/master/sample.png?raw=True)

I had found this somewhere on the internet previously, but couldn't find it now. I'll credit the original author when I find it again.

Art
  • 2,836
  • 4
  • 17
  • 34
3

If you have your images on Github, navigate to the image then right click on download button and copy link address:

enter image description here

Then you can add it in your README.md file:

![](https://github.com/your_username/your_repository/raw/master/images/img2.png)

It should be rendered properly both on Github and PyPi.

revy
  • 3,945
  • 7
  • 40
  • 85
0

The long_description_content_type should be text/x-rst if you use restructured text syntax (README.rst). Assuming that is what you are using based on ".. image::". If you save the image on GitHub and use that external link for the image then it works (typically something like raw.githubusercontent.com.... as described in one of the above answers).

It does work as shown in this pypi package: https://pypi.org/project/gammath-spot/

salyl bhagwat
  • 1