Reputation: 107221

How to add images to README.md on GitHub?

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?

Upvotes: 3515

Answers (30)

Harsh Narwariya

Reputation: 21

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

This is it

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.

Upvotes: 1

user3638471

Reputation:

It's much simpler than that.

Just add your image to the repository, and link to the filename, like so:

![screenshot](imageFolder/screenshot.png)

Upvotes: 356

Dimitrios Desyllas

Reputation: 10134

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:

Intialize git lfs for your each image type:

 git lfs *.png
 git lfs *.svg
 git lfs *.gif
 git lfs *.jpg
 git lfs *.jpeg

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
```
Copy paste any images into doc folder. Afterwards add them via git add command.
Commit and push.

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)

Upvotes: 6

chaimae

Reputation: 24

for me I resolved this problem in 2 steps:

I have uploaded the photo in the repository I get his url (which I will use in step 2)
![Screenshot (624)](here you have to insert the image url)

Hope it works :)

Upvotes: 0

Mahozad

Reputation: 24712

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

Upvotes: 106

ankushlokhande

Reputation: 1912

Use markdown syntax:

![ALT TEXT](../IMAGE_PATH/image.png)

![ALT TEXT](https://url_path/image.png)

You can also use online tools to generate the markdown for your content. Some of the tools which I used:

Upvotes: 5

Muhammad Ali

Reputation: 1340

Github supports many ways, use according to your needs.

1- Using Relative URLs:

If image is stored in the same repository as the README.md file then use this.

![Alt text](relative/path/to/image.png)

2- Using Absolute URLs:

use this when the image is hosted on a public server.

![Alt text](https://example.com/path/to/image.png)

3- Method no 3:

First upload the image directly to your GitHub repository and give the reference using a relative URL.
Then Drag and drop the image into the "Issues" section or any comment box in your repository to upload the image.
Once the image is uploaded, click on it to open the image file.
Copy the URL from the browser's address bar and use it in the README.md.

4- Using GitHub's Raw Content URL:

![Alt text](https://raw.githubusercontent.com/username/repository/master/path/to/image.png)

5- Using HTML Tag

<img src="https://example.com/path/to/image.png" alt="Alt text">

7- Sheild IO Badges:

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)

Hope it helps.

Upvotes: 2

user7551211

Reputation: 717

To upload images with size managing option:

<img src="a.jpg" alt="J" width="200"/>

Upvotes: 4

resultsway

Reputation: 13330

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)

Upvotes: 983

Muhammad Fahad Ado

Reputation: 117

This one works for me!!!.

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

alt text is the alternative text you wanna display incase the image URL doest not exist.

user_name is your GitHub username. reponame is your GitHub repo name.

Upvotes: 2

rohit

Reputation: 51

In the latest Github i have tried all the above ways and failed to show images on my readme page. The best that i found if it's a public repo is to use githubpages for the master or main branch and then reference the link in the readme file.

Steps:

In your repo go to settings -> under Code and automation select Pages
Select source and branch of your repo and click on save

now your repo should be hosted on (https://*username*.github.io/*reponame*/)

now you can simply add your image by

![Preview Image](https://*username*.github.io/*reponame*/images/logo.PNG)

Upvotes: 1

Muh-Osman

Reputation: 371

No need to write any code. readme file on GitHub now supports drag and drop

Open README.md file
Click Edit this file
Drag & drop your image
Click commit changes

Upvotes: 10

samadpls

Reputation: 133

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'/>

Upvotes: 9

Dzhud

Reputation: 55

You can as well drop the image at the appropriate part in the Read Me file.

Upvotes: 1

Dávid Horváth

Reputation: 4320

If you dont't want to "mess up" your branch's content with these images and it's not a problem for you that the link is absolute, then I recommend to use a separate orphan branch to store these images. In this case, images will be integrated with the repo while not included in the main content. In addition, you can use LFS for larger files (all the leading git hosts support LFS).

You can easily create an orphan branch in the command line:

git checkout --orphan images
git reset --hard
cp /path/to/your/image.jpg ./image.jpg
git add --all
git commit -m "Add some images"
git checkout master
git log -n 3 --all --graph

If everyhing is OK, push the new branch:

git push -u origin images

Then use the raw github URL of the image.

Upvotes: 0

Abdur Rahman

Reputation: 1583

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

Upvotes: 122

kushagra-aa

Reputation: 570

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

Upvotes: 20

siamsot

Reputation: 1575

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!

Upvotes: 20

Prashant Gaikwad

Reputation: 3810

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)

Upvotes: 12

Jwala Kumar

Reputation: 535

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.

Upvotes: 17

paulmelnikow

Reputation: 17218

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)

Upvotes: 83

Chinmay

Reputation: 940

If you want to show an image hosted at any website (say url is "http:// abc.def.com/folder/image.jpg") then in your README.md file use the below syntax:

![alt text](<http:// abc.def.com/folder/image.jpg>)

Just browse to the image in your browser (may be by clicking on the image). It can be any website, including yours or somebody else's github hosted image.
Copy the url from the browser address bar, that is your "image_url" to be used in above referred syntax.

For images hosted in your own github repository you can use relative path in addition to the above url format
![alt text](<path_relative_to_current_github_location/image.jpg>)

If the image is located in the same folder as the README.md file (special case of relative path url), then you can use:
![alt text](<image.jpg>)

Note the angular brackets "<" and ">" enclosing the url. Sometimes these are required for the url to work.

Upvotes: 1

Simon Lang

Reputation: 42775

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)

Upvotes: 3547

CrandellWS

Reputation: 2804

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

Upvotes: 7

Jason DeMorrow

Reputation: 579

There's yet another option I haven't seen mentioned. You can simply create another repository under your user or organization called "assets". Push your images to this repo and reference them from your other repos:

![alt text](https://raw.githubusercontent.com/my-org/assets/master/folder/logo.png)

I've done this in one of my repos and it suits me fine. I can version my README images for all of my projects independently of my code, but still keep them all in one place. No issues or branches or other easily misplaced artifacts required.

Upvotes: 3

Marium Jawed

Reputation: 419

Add image in your repository from upload file option then in README file

![Alt text]("enter repository image URL here")

Upvotes: 1

LuisDev99

Reputation: 1837

I have found another solution but quite different and i'll explain it

Basically, i used the tag to show the image, but i wanted to go to another page when the image was clicked and here is how i did it.

<a href="the-url-you-want-to-go-when-image-is-clicked.com" />
<img src="image-source-url-location.com" />

If you put it right next to each other, separated by a new line, i guess when you click the image, it goes to the tag which has the href to the other site you want to redirect.

Upvotes: 5

Shashankesh Upadhyay

Reputation: 365

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

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

helped by : adam-p

Upvotes: 15

Felix K.

Reputation: 15683

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

Upvotes: 38

Aditya Singh Rawat

Reputation: 93

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

Upvotes: 7

How to add images to README.md on GitHub?

Answers (30)

It's much simpler than that.

Github supports many ways, use according to your needs.

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

Display images from repo using:

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

append flag: ?sanitize=true&raw=true

use <img /> tag

Related Questions

append flag: `?sanitize=true&raw=true`

use `<img />` tag