Readme.md videos not working

[adnan-td]

Readme.md videos with links not showing up and just displaying links unlike in the website where you can play the video.

[D7EAD]

Hi!

Embedding a video in a README markdown file can be as simple as just pasting a link to the video! You can find an example README.md with a bunch of embedded media here, and you can view how they are embedded by clicking Raw at the top right!

If I've managed to help you, please consider Marking as Answer so others can more easily find the solution to this issue if they so encounter it.

[queenofcorgis]

Was @D7EAD able to help you @Adnan-S-Husain? Or are you still experiencing this?

[Zi-Tao]

@Adnan-S-Husain https://stackoverflow.com/questions/4279611/how-to-embed-a-video-into-github-readme-md

[henkjannl]

Dear all,

I have the same or a similar problem. In one of my repositories:

https://github.com/henkjannl/TravelWallet/blob/master/Readme.md

I have a subdirectory /images where a video named video.mp4 resides. I tried various ways to display the video in the readme, but none of them worked. The size of the video file is just 923 kB, so well below the 10Mb limit of a free account. I finally converted the video to gif which displays but looks underwhelming. Ways to incorporate the video that I tried:

<p align="center">
  <video src="images/video.mp4" width="500px"></video>
</p>

<video src="images/video.mp4" width="320" height="240" controls></video>

![non working video](images/video.mp4)

The video and gif can be found here:
https://github.com/henkjannl/TravelWallet/blob/master/images/video.mp4
https://github.com/henkjannl/TravelWallet/blob/master/images/video.gif

[henkjannl]

Thanks a lot for the clear and fast answer. Given the differences between platforms it is probably best if I try to improve the quality of the GIF.

[MarcelloPerathoner]

There's a workaround:

1. Open an issue on your repository. Don't save this issue.
2. Drag the .mp4 file into the issue editor. This creates an asset in your repo and returns the URL.
3. Copy the URL from the issue editor. Use this URL in the README.

This also works in a README.rst like this:

.. raw:: html

    <video src="URL"></video>

I personally find this workaround extremely annoying and don't understand why Github engineers can't get their act together. The logical place to put an explanatory video is in the repository along with the README.

[miguelcarrascoq]

works perfect! I have put it in my .md here https://github.com/miguelcarrascoq/yt-summary with:

<video src="https://github.com/user-attachments/assets/d0c3580a-7cbc-4ab1-ad04-42d4e35166bc" width="352" height="720"></video>

demo.mp4

note: is not mandatory to save the issue 😁

[roeniss]

I've encountered the same problem.

Edit README.md on repo (web), then directly drag-and-drop your video file from local to the editor. This way, GitHub will store it for you.

My problem was that I commited that video file into my repo and used that file link for README. So,

https://github.com/user-attachments/assets/${UUID} # it works
https://github.com/${user}/${repo}/raw/main/some/path/demo.mp4 # it doesn't work

[a2nath]

same problem that I probably forgot about from earlier this year, but revisited today. ChatGPT was also useless until you mentioned this

[roeniss]

happy to hear that!

[DayuanJiang]

Also note that the video size should be smaller than 10 MB.

[anasouardini]

Same issue in 2025

[mohammadazeemwani]

Same issue here..

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[albilaga]

same issue. but using this approach is working fine

I've encountered the same problem.

Edit README.md on repo (web), then directly drag-and-drop your video file from local to the editor. This way, GitHub will store it for you.

My problem was that I commited that video file into my repo and used that file link for README. So,

https://github.com/user-attachments/assets/${UUID} # it works
https://github.com/${user}/${repo}/raw/main/some/path/demo.mp4 # it doesn't work

but then I can't automate it

[mohammadazeemwani]

ya that is the issue;
using observation, I can tell that this particular UUID is generated when media is updated on github-servers using drag and drop when editing;
Obvious cz this https://github.com/user-attachments/assets/${UUID} is not tied to a specific user;
So I don't think there is any way to automate it.

[mohammadazeemwani]

One Way to Automate: we can inspect the POST that might be happening to upload the content and use the same signature to automate updating content.

[OrsoEric]

<!--` Failed to upload "2025-11-08-T2103_assembly_battery_regulator_480p.mp4" -->

Still the same problem in 2025. A video above 10MB can't be uploaded via drag grop

doesn't work with the file name

[sagagaga4]

I had that problem myself, the fix was really simple:)

1. try to compress the file moving it to mp4 format and compress it via sites such as "https://www.freeconvert.com/video-compressor". This will decrease the video quallity a bit but give you the video running smoothly.
2. Make sure you are adding it like so "
3. Try copying the video tag at the bottom of the file

[OrsoEric]

mp3 is an audio container, how can it store video? : O

[sagagaga4]

Oh that's my bad I meant MP4 instead of WAV .
But again try to compress the file several times until it is possible to publish it.
Whether it is a screen recording or an external video.

[OrsoEric]

the strategy is to make it smaller than 10 MB?

[sagagaga4]

The file size limit for uploading a video to README.md via drag-and-drop is 10 MB for free GitHub plans and 100 MB for paid GitHub plans that is why the i think that the proper strategy will be to decrease the file size

[nerraou]

There is a workaround:

I dragged the video from my laptop into the Readme file, which generated a link to it. I used the link as the src with the <video/> tag.

Check the link