Categories
github github-flavored-markdown markdown readme

How to add images to README.md on GitHub?

2890

Recently I joined GitHub. I hosted some projects there.

I need to include some images in my README File. I don’t know how to do that.

I searched about this, but all I got was some links which tell me to “host images on web and specify the image path in README.md file”.

Is there any way to do this without hosting the images on any third-party web hosting services?

4

2941

Try this markdown:

![alt text](http://url/to/img.png)

I think you can link directly to the raw version of an image if it’s stored in your repository. i.e.

![alt text](https://github.com/[username]/[reponame]/blob/[branch]/image.jpg?raw=true)

19

  • 254

    You should also consider using relative links

    – mgalgs

    Jan 21, 2014 at 18:00

  • 87

    Relative links are not a great use here, imagine your readme is also displayed on npm that does not host the image in this way – it needs to link to GitHub. Image srcs should be on the github.com domain, not the raw.github.com subdomain and not the raw.githubusercontent.com domain.

    Jun 24, 2014 at 6:25


  • 12

    I actually ended up going with the relative paths (which for me is just the name of the image file because I have everything in root). I had been maintaining 2 copies of the README.md, one for local installation in /usr/share/projectname/docs, and one for github. Now, I can just use the same README.md for both since the image filenames work fine in both cases. If I want to post a copy of parts of my README somewhere else, I’ll either have to host the images somewhere else or put in the raw.github.com url.

    Sep 30, 2014 at 23:23

  • 47

    GitHub themselves recommend relative paths: help.github.com/articles/relative-links-in-readmes One major downside of absolute paths is that, if the image gets moved in master, other branches that still point to the old URL will break.

    Oct 2, 2014 at 23:54

  • 9

    Currently suggested domain doesn’t seem to work and the link should be like this: https://github.com/[username]/[reponame]/blob/[branch]/image.jpg?raw=true

    Sep 11, 2018 at 10:02


781

You can also use relative paths like

![Alt text](relative/path/to/img.jpg?raw=true "Title")

Also try the following with the desired .fileExtention:

![plot](./directory_1/directory_2/.../directory_n/plot.png)

13

  • 40

    Yes. This is by far the easiest way unless you’re worried about performance.I’d note that this is relative to the directory not the repo, so if you have ‘myimage.png’ in the same dir as ‘about_pics.md’ then the markup is:![What is this](myimage.png)

    – Rich

    Mar 8, 2017 at 2:06


  • 9

    This is an awesome solution because 1) it works 2) images are also shown in a local viewer, with no need of internet access

    – Régis B.

    May 22, 2017 at 10:03

  • 2

    @Rich can you expand on your comment regarding performance. What performance issues are there with the relative path approach?

    – Lea Hayes

    Sep 9, 2017 at 18:41

  • 2

    This path is relative to what?

    – Dims

    Jul 15, 2018 at 14:46

  • 5

    As pointed out by Lee Crossley, you should avoid relative links because they break when your readme is displayed on npm. Instead, link to image src on github.com domain with “?sanitize=true” flag if the image format is something like SVG. See more details at this SO answer: stackoverflow.com/a/16462143/6798201

    Mar 28, 2019 at 12:02


371

  • You can create a New Issue
  • upload(drag & drop) images to it
  • Copy the images URL and paste it into your README.md file.

here is a detailed youTube video explained this in detail:

https://www.youtube.com/watch?v=nvPOUdz5PL4

13

  • 39

    As far as I understand you do not really need to save the issue. This way you do not really need those dummy tickets in the Issue Tracker. Question is if this is a “safe” method, meaning if GitHub will detect (after some time) that the image is orphaned and therefore delete it from the GitHub CDN ??

    – peterh

    Oct 23, 2016 at 9:11

  • 5

    This answer worked perfectly for me and didn’t need to save the new issue within the repo. I’ve found a video on Youtube that explains that in details: youtube.com/watch?v=nvPOUdz5PL4.

    Jun 14, 2018 at 14:10


  • 1

    This answer works, and requires little effort. The issue can be discarded, but the URL for the image persists. The image URL is in the form of: user-images.githubusercontent.com

    – Sabuncu

    Nov 29, 2018 at 19:48

  • 7

    This is a great trick! But does anyone know the answer to @peterh’s question? Will GitHub periodically purge images that are orphaned (i.e. doesn’t have an issue attached to it)?

    Dec 6, 2018 at 17:49

  • 1

    @JohnnyOshika I doubt anyone outside of github could definitively answer that. It might be dependent on what “user-images.githubusercontent.com” is used for. If it is only for images uploaded to comments, then it is plausible that they could scan for the missing data relation and remove the image. If its more general, it may be difficult to definitely determine that there are no references to the file, making it either computationally expensive or challenging to determine that it can be deleted without issues.

    Feb 21, 2019 at 22:07