How to add images to README.md on GitHub?

Question

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?

Solution 1

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)

Solution 2

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)

Solution 3

• 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

Solution 4

You can also add images with simple HTML tags:

<p align="center">
  <img src="your_relative_path_here" width="350" title="hover text">
  <img src="your_relative_path_here_number_2_large_name" width="350" alt="accessibility text">
</p>

Solution 5

Many of the posted solutions are incomplete or not to my taste.

• An external CDN like imgur adds another tool to the chain. Meh.
• Creating a dummy issue in the issue tracker is a hack. It creates clutter and confuses users. It's a pain to migrate this solution to a fork, or off GitHub.
• Using the gh-pages branch makes the URLs brittle. Another person working on the project maintaining the gh-page may not know something external depends on the path to these images. The gh-pages branch has a particular behavior on GitHub which is not necessary for hosting CDN images.
• Tracking assets in version control is a good thing. As a project grows and changes it's a more sustainable way to manage and track changes by multiple users.
• If an image applies to a specific revision of the software, it may be preferable to link an immutable image. That way, if the image is later updated to reflect changes to the software, anyone reading that revision's readme will find the correct image.

My preferred solution, inspired by this gist, is to use an assets branch with permalinks to specific revisions.

git checkout --orphan assets
git reset --hard
cp /path/to/cat.png .
git add .
git commit -m 'Added cat picture'
git push -u origin assets
git rev-parse HEAD  # Print the SHA, which is optional, you'll see below.

Construct a "permalink" to this revision of the image, and wrap it in Markdown.

Looking up the commit SHA by hand is inconvenient, however, so as a shortcut press Y to a permalink to a file in a specific commit as this help.github page says.

To always show the latest image on the assets branch, use the blob URL:

https://github.com/github/{repository}/blob/assets/cat.png 

(From the same GitHub help page File views show the latest version on a branch)

View more solutions

Comments

[mgalgs]

You should also consider using relative links

[Lee Crossley]

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.

[Colin Keenan]

I just tried it by right-clicking on an image in my project, copying the link, and putting it in the README.md. That gave me the github.com domain as you suggest, but although it displayed fine on github, it did not display fine on my local copy. On the other hand, using raw.github.com and deleting "blob/" from the path displayed fine on my local computer. So, I would say the accepted answer here is correct as is.

[Colin Keenan]

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.

[Jack O'Connor]

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.

[android developer]

How would you create a clickable image , which goes to a certain URL ?

[X.Creates]

When you using HTML tag(s) inside you markdown file. It will be ignored by Pandoc, a universal document converter.

[Cerin]

Note, Github's default markdown interpreter wraps the image inside an anchor tag, which may not be what you always want.

[peterh]

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 ??

[Rich]

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)

[Régis B.]

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

[williaster]

I think that relative links break on npm package descriptions, which pull from README.mds

[Joe Hill]

This is the easiest way to add them in my opinion. Simply drag them into the box, copy the address and paste it into your readme with captions below. Boom, you're done.

[Lea Hayes]

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

[Rich]

Oh, I just thought that since this retrieves the image from the repo, it's intrinsically going to do more work than having the images on a CDN or whatever.

[Andrea Bergonzo]

What is the differente between [[link]] and ![alt-text](link)

[Ryan]

I found that I have to use the address listed when going to that image in Github which is different from what people are saying here. ![title](https://github.com/username/reponame/blob/master/su‌​bfolders.../filename‌​.jpg) Notice the "blob" term in the filename. The answers here didn't work for me in 2017.

[mohessaid]

You can use relative links to show images in your readme file on Github. Check this example.

[Cerin]

This auto-wraps the image in <p><a>...</a></p> tags, which isn't ideal. Is there any way to disable that?

[Francislainy Campos]

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.

[Alexis Wilke]

This is best so it can be centered or placed on one side (for smaller images, at least.)

[Dims]

This path is relative to what?

[iGatiTech]

@captainclam I have implemented your solution and it's worked like a charm. But I am facing one issue, gif is playing only once. While in my local machine it is playing on repeat mode. I don't know why GitHub plays it only once. Any Help is appreciated! Thank you

[resultsway]

Your github folder is the root so its relative to the root of the github folder. if you have $HOME/mygithub_folder/doc/img.jpg? then just use doc/img.jpg in your $HOME/mygithub_folder/README.md

[friederbluemle]

How do you specify the relative path? It's not relative to README.md (in all cases?).

[Slavik Shynkarenko]

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

[Dan]

Love this tool!

[dojuba]

This is a good complement to the accepted answer. Assets are tracked, images are not in master, no clutter. Just be careful about the git reset --hard; make sure changes were committed.

[xiaodai]

relative to what?

[Dims]

@resultsway so relative/path/to/img.jpg is the same as /relative/path/to/img.jpg?

[Sabuncu]

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...

[Johnny Oshika]

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)?

[paulmelnikow]

In the wild on your machine. You can point it to wherever the file happens to be (~/Downloads, /tmp, etc.).

[Biswajit Das]

Perfect and crisp.

[KillerRabbit]

The ?raw=true was the secret sauce that finally got this to work for me.

[amc]

In the event that you do not need a caption you can leave it blank. An example may be easier to understand in this case: ![](https://url/figure.png)

[yourbuddypal]

@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.

[kingthorin]

Has anyone figured out how to get this working in a preview or PR?

[AlienKevin]

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

[mhenry1384]

It didn't work for me until I removed the query string.

[cdsaenz]

This has worked for me. Having an image in a folder "apps" under the README.md I've used: ![](images/ss_apps.png)

[cdsaenz]

It's relative to the README.md position. I have that readme in a docs folder and then images below with my screenshots, so I do ![Image](images/ss_apps.png)

[Raja]

The fact that this is the easiest way should be an embarrassment to GitHub. After 15 minutes messing about with Wiki, gh-pages and github.io, I'm just going to use this solution (again).

[mhucka]

The use of tables is irrelevant to the topic of the OP's question.

[JChat]

Awesome. I found this to be the easiest too.

[Danila Polevshchikov]

At least for .png and raw.githubusercontent.com sanitize=true doesn't work and should be removed. raw=true works fine. github.com/sphinxy/AppDynamics.Playground/blob/master/README‌​.md

[Dhiren Hamal]

Relative path worked for me in github repository ![alt text](/resources/images/roadmap.png)

[UpaJah]

adding screenshots of an app can be done this way nicely, thanks

[Harsh Patel]

You can Upload image to Repo and then go to image, click on download and get the link and add it to the readme file: ![alt text](link to download image)

[Luk Aron]

it works, Actually, I think this answer should be accepted

[Luk Aron]

I just would like to say that, it is not safe even for the hosting service in this way, you don't even know which day suddenly they will stop hosting your image. Simply put the image in the repo and follow this. stackoverflow.com/a/53771381/10189759

[Tammi]

I am surprised that only Aditya mentioned that spaces are a problem, and in a rather stupid way too - no errors, but your syntax is simply displayed like no such feature would even exist. Upvote from me for mentioning this.

[Shridutt Kothari]

I too love this tool, this should be Git's default feature!!

[Welcor]

@LukAron you think, or you know it is not save?

[Luk Aron]

@Blechdose Just by my first intuition, the possibility of losing that host image is considerable.

[jeffmcneill]

Use CSS instead of Tables, it will rock your world.

[Thomas Browne]

This is the only one that worked flawlessly for me. No confusion about paths, whether "master" refers to a directory or a branch, where the root start is, etc. Only caveat is Firefox (72) does not allow you to open image in separate tab so this is Chrome only for now I think.

[Rory O'Kane]

rawgit.com shut down in 2018 and should not be used any more; you should remove it from this answer. raw.githubusercontent.com, which you also mention, is the closest alternative.

[Shadoninja]

I swear I remember there being a directory that you can make that doesn't show up on Github. Until I can track that down, this post seems like the next best thing to use. Thanks!

[phi]

Thanks, a relative path of images/file.png worked for me. Just to point out: I had to add ?raw=true to the URL. Otherwise the image was not displayed (but a broken icon).

[Abhinav Dobhal]

Here (screenshot.png) is relative path from readme.md file. e.g., I had (images/landing_page.png)

[Samega 7Cattac]

uploading to an issue isn't needed, upload to ur repo (recommended) or use an image hosting provider.

[Kavindu Gayantha]

adding more images like this is not worked for me. Is there any other way to do that?

[Mattwmaster58]

strongly suggest adding alt-text to make things more accessible for people using screenreaders

[Ashish Kamble]

Raw version comes with?token=TOKEN it stops working after a while

[Ari K]

This is awesome!

[ArtuX]

I don't get what is the advantage of creating new branch for assets. Why not just keep the assets in the same branch, with files that use those assets?

[carloswm85]

There's a permalink option for images in the repos. Go to the image, and you'll find it among the options of it.

[Joonas]

I've used this for image hosting and have had the images disappear without warning. Highly recommend hosting within a repo over this

[paulmelnikow]

There's less clutter that way.

[Leherenn]

Also works for Gitlab.

[Andreea]

This is amazing!

[user75648]

Really the most useful answer. Even I was searching for this, but most of the answers I got involved uploading the image somewhere like in issues/repo etc. & providing a link to it. This one really helps!

[gmdev]

This might be obvious to others, but make sure you're editing the README file on the GitHub repository on the web. It won't work in your local IDE, you have to manually edit the README file on the repo and then drag and drop. Thanks for the answer!

[udorb b]

this best way edit read me > copy pic > paste > save

[The Dembinski]

I can confirm this worked - the editor in github handled cmd+v very cleanly and uploads the image

[Bidisha Das]

This is the most important answer imo