There are three ways to put a demo in a README, and they behave very differently: one plays inline with sound, one autoplays silently, one is just a picture that links out. Here is how each works, the size limits GitHub documents, and what I could and could not verify.
If you want to add a video to a GitHub README, the short answer is: drag an .mp4 or .mov into a GitHub text box, wait for the link it gives you, and put that link in your README. The long answer is that there are two other routes (a GIF, or a thumbnail that links to YouTube or Loom), and the right one depends on whether you need sound, autoplay or a file bigger than 10 MB. I build ReelMint, a video studio for developers, so I have a stake in demo videos existing at all. This post is the how-to I wanted, with the limits checked against GitHub's own docs on 3 November 2026.
There is also a fourth, less useful option: committing the video file into the repository or attaching it to a release. I cover where that fits in the comparison section.
GitHub's docs on attaching files say you can attach a video by dragging and dropping it into the comment box, and list the supported video formats as .mp4, .mov and .webm. After the upload, "the text field is updated to show the anonymized URL for the file". That page covers issues, pull requests and comments. It does not mention READMEs, so the README steps below combine the documented upload with what other maintainers have reported working.
The steps:
Either of these goes in your README.md:
https://github.com/user-attachments/assets/REPLACE-WITH-YOUR-UPLOAD-ID
<video src="https://github.com/user-attachments/assets/REPLACE-WITH-YOUR-UPLOAD-ID" controls width="720"></video>The size limits are the part people get wrong. GitHub's docs state 10 MB for videos uploaded to a repository owned by a user or organization on a free plan, and 100 MB on a paid plan. Images and GIFs are capped at 10 MB, and other files at 25 MB. Note the wording: it is the plan of the repository owner, not of the person uploading.
Two behaviours worth knowing, both reported by maintainers rather than documented by GitHub. First, the asset URL is not a public link: one project found that a thumbnail linking straight to a user-attachments URL gave anonymous visitors a 404, because GitHub serves these only when embedded in rendered Markdown. Second, the HeyGen Hyperframes project tried an MP4 in a video tag, found GitHub strips autoplay and loop so it needs a click, and switched its README hero to an animated WebP image instead.
The docs also say files in public repositories can be accessed without authentication, while for private and internal repositories only people with access to the repository can view them. So an upload into a public repo's comment box is effectively public, even if you never submit the comment.
A GIF is just an image, so it needs no special handling. Commit it to the repository and reference it with a relative path, which GitHub's docs recommend over absolute links for images in the repo:
<img src="docs/demo.gif" alt="Demo of the CLI" width="720">The upside is real: it autoplays and loops without a click, and it renders everywhere Markdown does, including npm and package registries that drop video tags. The Hyperframes PR above noted that most non-GitHub renderers, npmjs.com among them, strip the video tag.
The downsides: no audio, a 256-colour palette that makes gradients and syntax highlighting look rough, and large files for anything longer than a few seconds. Because GitHub caps images and GIFs at 10 MB on upload, a long terminal session will not fit through the upload path, though a GIF committed into the repo is subject to the repository file limits instead: GitHub warns above 50 MiB and blocks files larger than 100 MiB.
If you are making the GIF from a terminal session, a tool such as vhs can write one directly. Its README lists GIF, MP4 and WebM as output formats and requires ttyd and ffmpeg on your PATH. More on that in the last section.
This is the oldest trick and still the only one with no size cap: a normal image, wrapped in a normal link. The pattern is a Markdown image inside a Markdown link:
[](https://www.youtube.com/watch?v=VIDEO_ID)Replace VIDEO_ID with the 11-character ID from your YouTube URL. I checked the img.youtube.com thumbnail URLs for hqdefault.jpg and maxresdefault.jpg against one public video today and both returned 200. maxresdefault.jpg is not generated for every video, so hqdefault.jpg is the safer default. For Loom, take a screenshot of the first frame, commit it to your repo, and use that path as the image, because I did not verify a stable public thumbnail URL for Loom.
What you give up is inline playback: the reader clicks, leaves GitHub and lands on the video site. What you get is a platform that handles hosting, streaming, captions and a link you can share elsewhere.
On the fourth option: you can commit a video file to the repo, but a relative path in a video tag has been reported not to render in a README, and GitHub warns at 50 MiB and blocks above 100 MiB, with a recommended repository size of ideally under 1 GB. Release assets are a better home for large files, since each file can be up to 2 GiB with no limit on a release's total size, but the README link then points at a download, not an inline player. I did not test whether a release-asset MP4 plays inline, so do not count on it.
Everything above assumes you already have a file. Three honest ways to get one:
Plenty of the time it is the wrong tool. If you want a 10 second looping clip of one command running, record it with vhs or a screen recorder; that is faster and shows the real output. ReelMint produces a composed, narrated video, not a capture of your actual terminal, and it is built around vertical 9:16 Shorts, so for a widescreen README banner a screen recording is the better fit. Also, a first reel is not instant: our own measurement for a 60 to 90 second reel is 45 to 60 minutes elapsed, 10 to 20 minutes of it hands-on, from one person who built the product.
Where it does fit: a project with a story to tell in 60 to 90 seconds, a README that already works as a script outline, and a plan to publish the same video on YouTube Shorts as well as in the repo. You can try the free tier with your own API keys; see pricing.
Not reliably as an MP4. GitHub's docs do not document autoplay for video, and maintainers report that GitHub strips autoplay and loop from video tags in Markdown, so viewers have to click play. GIFs and animated WebP images, being images, do animate on their own.
GitHub's attaching-files docs set 10 MB for videos uploaded to repositories owned by a user or organization on a free plan and 100 MB on a paid plan. Images and GIFs are capped at 10 MB, other files at 25 MB. Files committed into the repo follow different limits: a warning at 50 MiB and a block at 100 MiB.
Use an mp4 uploaded through GitHub when you need sound, sharper text or a longer clip, and accept that it needs a click. Use a GIF when you want a silent, instant loop that also renders on npm and other sites that strip video tags. For anything past a minute, link a thumbnail to YouTube or Loom instead.
If you are launching an open-source project, promoting an open-source project with a demo video covers what to do with the video once the README has it.
Get one practical MCP-video tip when we publish the next post — no more than that.
Point your agent at a video pipeline that speaks MCP and make one small thing. Free founding-creator pilot — your keys, no watermarks.
Create your studio — free pilot