DEV Community

Cover image for How to add a video to your GitHub README
Joel P. Mugalu
Joel P. Mugalu

Posted on • Updated on

How to add a video to your GitHub README

As you might already know the version of Markdown that GitHub uses does not support adding videos. Although you might find work arounds if you search hard enough, the closest you'll get to is embedding a YouTube video in your markdown file. But what if you have a custom video? A video on your device?

Well, there's a workaround, it won't enable you to upload the video but you'll get the same results. The thing is GitHub READMEs work perfectly with GIFs. GIF is a bitmap graphical image format. So what you get isn't necessarily a video but the result is relatively similar.

Now all you have to do is obtain the desired video and use a tool such as CloudConvert to convert the video to a gif.

However, it's worth noting that the longer the video the bigger the size and you might experience some lagging depending on the type of video and the converting software used. Besides this you should generally get good results.

After converting the video to a GIF. All you have to do is create a GitHub repository with the same name as your GitHub username. For example my GitHub username is codingknite so the new repository would also be called codingknite.

Then simply add the GIF in your file the same way you would add an image

![caption](link to image / GIF)
Enter fullscreen mode Exit fullscreen mode

And that's all. Push your files to your GitHub account and you should have an impressive README.


Recently, GitHub added support for different media formats. Therefore you do not need to use a third party converter to convert your video to GIF format.

With the latest update all you have to do is open your markdown editor in GitHub and just drag your media into the editor and it should be added to your README.

You can checkout mine to see what I chose. Feel free to also connect with me on Twitter or LinkedIn.

Other articles you may like

Discussion (4)

mellen profile image
Matt Ellen

That's great! You can also use the webp format too. It is widely supported, and has much better compression compared to GIFs.

labib profile image

just figured out how to upload videos.. thanks Matt !!!!

codingknite profile image
Joel P. Mugalu Author

That's great Matt. I didn't know that. Am going to try that myself. Thanks

sampritimitra profile image
Sampriti Mitra • Edited on

Thanks Matt! Wasn't working with mov, will try this