3128

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?

3

43 Answers 43

3190

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)
22
  • 276
    You should also consider using relative links
    – mgalgs
    Jan 21, 2014 at 18:00
  • 91
    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
  • 50
    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
868

You can also use relative paths like

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

Also try the following with the desired .fileExtention:

![plot](./directory_1/directory_2/.../directory_n/plot.png)
14
  • 46
    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
  • 10
    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
  • 6
    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
    – AlienKevin
    Mar 28, 2019 at 12:02
391
  • 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

14
  • 43
    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
  • 7
    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
  • 2
    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). Jul 11, 2019 at 3:21
255

It's much simpler than that.

Just upload your image to the repository root, and link to the filename without any path, like so:

![Screenshot](screenshot.png)
7
  • 27
    No, I don't think adding screenshots to the git repo is a good practice. Especially not at the root. Ahmad Ajmi's answer is much better
    – Arnaud P
    Oct 10, 2016 at 12:27
  • 48
    Not at the root but you can easily adapt this to docs/images or what ever, small png screenshots are ok IMHO Jan 23, 2017 at 10:12
  • 8
    This should be the accepted solution, esp. with Christophe's suggestion to put the images under the doc/ tree/
    – Mike Ellis
    Apr 11, 2017 at 21:01
  • 1
    perfect..!! if the png is in another folder. Simply, add the path "folderName/screenshot.png"
    – Soumen
    Mar 22, 2018 at 16:43
  • I found your answer useful for my case: I'm on Gitlab and I use logo.png pictures at the root of the repo to set an avatar to the repo. I wanted to include this pic to the README.md. Oct 31, 2018 at 10:02
124

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>
3
  • 2
    When you using HTML tag(s) inside you markdown file. It will be ignored by Pandoc, a universal document converter.
    – Dummy
    Apr 6, 2016 at 5:37
  • 2
    This is best so it can be centered or placed on one side (for smaller images, at least.) Jun 21, 2018 at 4:17
  • 1
    How do you specify the relative path? It's not relative to README.md (in all cases?). Sep 10, 2018 at 18:45
81

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)

5
  • 3
    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.
    – dojuba
    Sep 30, 2018 at 9:40
  • In the wild on your machine. You can point it to wherever the file happens to be (~/Downloads, /tmp, etc.). Dec 13, 2018 at 19:44
  • 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!
    – Shadoninja
    May 3, 2020 at 0:45
  • 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?
    – ArtuX
    May 19, 2021 at 9:04
  • There's less clutter that way. Jun 10, 2021 at 16:25
68

You can also insert animated SVG images in the markdown file like any other format.
It can be a good alternative to GIF images.

![image description](relative/path/in/repository/to/image.svg)
OR
<img src="relative/path/in/repository/to/image.svg" width="128"/>

Example (assuming the image is in assets directory in the repository):

![My animated logo](assets/my-logo.svg)

Result:


To use different images based on GitHub dark/light theme see this post.

4
  • how do I reduce the width use I use ![image description](relative/path/in/repository/to/image.svg) Aug 6, 2022 at 19:15
  • 1
    @DanielSogbey I think you should use the HTML element <img> and set the width attribute like <img src="relative/..." width="100px" />.
    – Mahozad
    Aug 7, 2022 at 7:10
  • @DanielSogbey can I use external url with img tag? Mine doesn't working
    – Sunlight
    Aug 29, 2022 at 9:47
  • @SunPodder sorry for coming in late, an external url should work perfectly Aug 29, 2022 at 18:01
65

Very Simple : Can be done using Ctrl + C/V

Most of the answers here directly or indirectly involve uploading the image somewhere else & then providing a link to it.

It can be done very simply by just copying any image and pasting it while editing Readme.md

  • Copying the image - You can just click on the image file and use Ctrl + C or may copy the screenshot image to your clipboard using the snipping tool
  • You can then simply do Ctrl + V while editing Readme.md

Guithub will automatically upload it to user-images.githubusercontent.com and a link to it will be inserted there

4
  • 6
    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!
    – user75648
    Dec 13, 2021 at 14:37
  • 3
    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!
    – gmdev
    Mar 9, 2022 at 13:13
  • this best way edit read me > copy pic > paste > save
    – udorb b
    Apr 6, 2022 at 10:21
  • 2
    I can confirm this worked - the editor in github handled cmd+v very cleanly and uploads the image Apr 8, 2022 at 15:18
37

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

I created a small wizard that allows you to create and customize simple image galleries for your GitHub repository's readme: See ReadmeGalleryCreatorForGitHub.

The wizard takes advantage of the fact that GitHub allows img tags to occur in the README.md. Also, the wizard makes use of the popular trick of uploading images to GitHub by drag'n'dropping them in the issue area (as already mentioned in one of the answers in this thread).

enter image description here

0
35

Commit your image (image.png) in a folder (myFolder) and add the following line in your README.md:

![Optional Text](../master/myFolder/image.png)

25

Basic Syntax

![myimage-alt-tag](url-to-image)

Here:

  1. my-image-alt-tag : text that will be displayed if image is not shown.
  2. url-to-image : whatever your image resource is. URI of the image

Example:

![stack Overflow](http://lmsotfy.com/so.png)

This will look like the following:

stack overflow image by alamin

24
  • Create an issue regarding adding images
  • Add the image by drag and drop or by file chooser
  • Then copy image source

  • Now add ![alt tag](http://url/to/img.png) to your README.md file

Done!

Alternatively you can use some image hosting site like imgur and get it's url and add it in your README.md file or you can use some static file hosting too.

Sample issue

1
  • 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.
    – Joe Hill
    Jul 19, 2017 at 3:57
21

You can now drag and drop the images while editing the readme file.

Github will create a link for you which will be in the format of:

https://user-images.githubusercontent.com/******/********.file_format

Alternatively, at the bottom of the file, it says "Attach files by dragging & dropping, selecting or pasting them". If you click on that one, it will give you an option to upload a file directly or you can just paste it!

20

Just add an <img> tag to your README.md with relative src to your repository. If you're not using relative src, make sure the server supports CORS.

It works because GitHub support inline-html

<img src="/docs/logo.png" alt="My cool logo"/>
# My cool project and above is the logo of it

Observe here

20

You Can use

![A test image](image.png)

Where ![A test image] is your alt text and (image.png) is the link to your image.


You can have the image on a cloud service or other online image hosting platforms Or you can provide the image link from the repository if it is in the repo


You can also make a specific folder inside your repository dedicated to your readme images

16

Step by step process, First create a folder ( name your folder ) and add the image/images that you want to upload in Readme.md file. ( you can also add the image/images in any existing folder of your project. ) Now,Click on edit icon of Readme.md file,then

![](relative url where images is located/refrence_image.png)  // refrence_image is the name of image in my case.

After adding image, you can see preview of changes in the, "Preview Changes" tab.you will find your image here. for example like this, In my case,

![](app/src/main/res/drawable/refrence_image.png)

app folder -> src folder -> main folder -> res folder -> drawable folder -> and inside drawable folder refrence_image.png file is located. For adding multiple images, you can do it like this,

![](app/src/main/res/drawable/refrence_image1.png)
![](app/src/main/res/drawable/refrence_image2.png)
![](app/src/main/res/drawable/refrence_image3.png)

Note 1 - Make sure your image file name does not contain any spaces. If it contain spaces then you need to add %20 for each space between the file name. It's better to remove the spaces.

Note 2 - you can even resize the image using HTML tags, or there are other ways. you can google it for more. if you need it.

After this, write your commit changes message, and then commit your Changes.

There are many other hacks of doing it like, create a issue and etc and etc. By far this is the best method that I have came across.

2
  • adding more images like this is not worked for me. Is there any other way to do that? Oct 21, 2020 at 4:54
  • strongly suggest adding alt-text to make things more accessible for people using screenreaders Jan 5, 2021 at 3:14
14

Use tables to stand out, it will give separate charm to it

Table Syntax is:

Separate each column cell by symbol |

and table header (First row) by 2nd row by ---


| col 1      | col 2      |
|------------|-------------|
| image 1 | image 2 |

output

enter image description here


Now just put <img src="url/relativePath"> at image 1 and image 2 if you are using two images


Note: if using multiple images just include more columns, you may use width and height attribute to make it look readable.

Example


| col 1      | col 2      |
|------------|-------------|
| <img src="https://media.wired.com/photos/5926db217034dc5f91becd6b/master/w_582,c_limit/so-logo-s.jpg" width="250"> | <img src="https://mk0jobadderjftub56m0.kinstacdn.com/wp-content/uploads/stackoverflow.com-300.jpg" width="250"> |

Spacing does not matter

Output image

enter image description here

helped by : adam-p

3
  • 6
    The use of tables is irrelevant to the topic of the OP's question.
    – mhucka
    Sep 2, 2019 at 19:18
  • 1
    adding screenshots of an app can be done this way nicely, thanks
    – UpaJah
    Oct 22, 2019 at 8:18
  • Use CSS instead of Tables, it will rock your world. Feb 25, 2020 at 5:56
12

In new Github UI, this works for me -

Example - Commit your image.png in a folder (myFolder) and add the following line in your README.md:

![Optional Text](../main/myFolder/image.png)
11

You can just do:

git checkout --orphan assets
cp /where/image/currently/located/on/machine/diagram.png .
git add .
git commit -m 'Added diagram'
git push -u origin assets

Then you can just reference it in the README file like so:

![diagram](diagram.png)

1
  • Note that GitHub supports various diagram languages in .md files. So you can write the code for the diagrams right in the markdown files, no need to embed rendered image of the diagram. Jan 24 at 21:14
9

JUST THIS WORKS!!

take care about your file name uppercase in tag and put PNG file inroot, and link to the filename without any path:

![Screenshot](screenshot.png)
1
  • Here (screenshot.png) is relative path from readme.md file. e.g., I had (images/landing_page.png) Sep 6, 2020 at 3:14
9

Although GitHub markdown can also add pictures I will suggest you use an HTML IMG tag
GitHub Markdown

![me](https://github.com/samadpls)

HTML TAG

<img src='https://github.com/samadpls'/>
8

I usually host the image on the site, this can link to any hosted image. Just toss this in the readme. Works for .rst files, not sure about .md

.. image:: https://url/path/to/image
   :height: 100px
   :width: 200 px
   :scale: 50 %
8

I have solved this problem. You only need to refer to someone else's readme file.

At first,you should upload an image file to github code library ! Then direct reference to the address of the image file .



enter image description here

enter image description here

8

In my case i use imgur and use the direct link this way.

![img](http://i.imgur.com/yourfilename.png)
8

You can link to images in your project from README.md (or externally) using the alternative github CDN link.

The URL will look like this:

https://cdn.rawgit.com/<USER>/<REPO>/<BRANCH>/<PATH>/<TO>/<FILE>

I have an SVG image in my project, and when I reference it in my Python project documentation, it does not render.

Project link

Here is the project link to the file (does not render as an image):

https://github.com/jongracecox/anybadge/blob/master/examples/awesomeness.svg

Example embedded image: image

Raw link

Here is the RAW link to the file (still does not render as an image):

https://raw.githubusercontent.com/jongracecox/anybadge/master/examples/awesomeness.svg

Example embedded image: image

CDN link

Using the CDN link, I can link to the file using (renders as an image):

https://cdn.rawgit.com/jongracecox/anybadge/master/examples/awesomeness.svg

Example embedded image: image

This is how I am able to use images from my project in both my README.md file, and in my PyPi project reStructredText doucmentation (here)

7

There are 2 simple way you can do this ,

1) use HTML img tag ,

2) ![](the path where your image is saved/image-name.png)

the path would you can copy from the URL in the browser while you have opened that image. there might be an issue occur of spacing so make sure if there is any space b/w two words of path or in image name add-> %20. just like browser do.

Both of them will work , if you want to understand more you can check my github -> https://github.com/adityarawat29

2
  • This has worked for me. Having an image in a folder "apps" under the README.md I've used: ![](images/ss_apps.png)
    – cdsaenz
    Jul 3, 2019 at 22:28
  • 1
    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.
    – Tammi
    Nov 25, 2019 at 12:18
7

This Answer can also be found at: https://github.com/YourUserAccount/YourProject/blob/master/DirectoryPath/ReadMe.md

Display images from repo using:

prepend domain: https://raw.githubusercontent.com/

append flag: ?sanitize=true&raw=true

use <img /> tag

Eample url works for svg, png, and jpg using:
  • Domain: raw.githubusercontent.com/
  • UserName: YourUserAccount/
  • Repo: YourProject/
  • Branch: YourBranch/
  • Path: DirectoryPath/
  • Filename: example.png

Works for SVG, PNG, and JPEG

 - `raw.githubusercontent.com/YourUserAccount/YourProject/YourBranch/DirectoryPath/svgdemo1.svg?sanitize=true&raw=true`

Working example code displayed below after used:

**raw.githubusercontent.com**:
<img src="https://raw.githubusercontent.com/YourUserAccount/YourProject/master/DirectoryPath/Example.png?raw=true" />

<img src="https://raw.githubusercontent.com/YourUserAccount/YourProject/master/DirectoryPath/svgdemo1.svg?sanitize=true&raw=true" />

raw.githubusercontent.com:

Thanks: - https://stackoverflow.com/a/48723190/1815624 - https://github.com/potherca-blog/StackOverflow/edit/master/question.13808020.include-an-svg-hosted-on-github-in-markdown/readme.md

3
6

I am just extending or adding an example to the already accepted answer.

Once you have put the image on your Github repo.

Then:

  • Open the corresponding Github repo on your browser.
  • Navigate to the target image file Then just open the image in a new tab. Opening the image in a new tab
  • Copy the url Copy the url from the browser tab
  • And finally insert the url to the following pattern ![alt text](https://raw.githubusercontent.com/username/projectname/branch/path/to/img.png)

On my case it is

![In a single picture](https://raw.githubusercontent.com/shadmazumder/Xcode/master/InOnePicture.png)

Where

  • shadmazumder is my username
  • Xcode is the projectname
  • master is the branch
  • InOnePicture.png is the image, On my case InOnePicture.png is in the root directory.
1
  • 1
    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. Apr 14, 2020 at 15:32
5

In my case I wanted to show a print screen on Github but also on NPM. Even though using the relative path was working within Github, it wasn't working outside of it. Basically, even if I pushed my project to NPM as well (which simply uses the same readme.md, the image was never showing.

I tried a few ways, at the end this is what worked for me:

![Preview](https://raw.githubusercontent.com/username/project/master/image-path/image.png)

I now see my image correctly on NPM or anywhere else that I could publish my package.

0
5

In case you need to upload some pictures for documentation, a nice approach is to use git-lfs. Asuming that you have installed the git-lfs follow these steps:

  1. Intialize git lfs for your each image type:

    git lfs *.png
    git lfs *.svg
    git lfs *.gif
    git lfs *.jpg
    git lfs *.jpeg
    
  2. Create a folder that will be used as image location eg. doc. On GNU/Linux and Unix based systems this can be done via:

    cd project_folder
    mkdir doc
    git add doc
    
  3. Copy paste any images into doc folder. Afterwards add them via git add command.

  4. Commit and push.

  5. The images are publicly available in the following url:

    https://media.githubusercontent.com/media/^github_username^/^repo^/^branch^/^image_location in the repo^

Where: * ^github_username^ is the username in github (you can find it in the profile page) * ^repo_name^ is the repository name * ^branch^ is the repository branch where the image is uploaded * ^image_location in the repo^ is the location including the folder that the image is stored.

Also you can upload the image first then visit the location in your projects github page and navigate through until you find the image then press the download button and then copy-paste the url from the browser's address bar.

Look this from my project as reference.

Then you can use the url to include them using the markdown syntax mentioned above:

![some alternate text that describes the image](^github generated url from git lfs^)

Eg: Let us suppose we use this photo Then you can use the markdown syntax:

![In what order to compile the files](https://media.githubusercontent.com/media/pc-magas/myFirstEnclave/master/doc/SGX%20Compile%20workflow.png)

Not the answer you're looking for? Browse other questions tagged or ask your own question.