How to Put a Product Demo Video in a GitHub README

The best way to put a product demo video in a GitHub README is to upload a short H.264 MP4 (or MOV or WebM) through the README editor on github.com, so GitHub hosts the file and shows an inline player. A GIF works for silent loops under 10 MB. A YouTube link works when the video is longer than the upload limit or you want comments and analytics on YouTube.

What is the best format for a demo in a GitHub README?#

Upload a short MP4 in H.264. GitHub's own attaching files docs list .mp4, .mov and .webm as supported video types, and they recommend H.264 because browser support for other codecs varies. That MP4 is what shows an inline player on the README for visitors who open the repo.

Use a GIF when you want a silent loop under 10 MB and you do not need a voiceover. Use a YouTube link when the demo needs more time than the upload limit allows, or when you care about YouTube search and comments.

How do you add an MP4 to a GitHub README?#

1. Export a short demo as 1080p MP4 in H.264 with AAC audio. Aim for a clip that stays under the plan limit after compression.
2. Open the README.md file on github.com and click Edit.
3. Drag the MP4 into the editor, or use the attach control under the field. GitHub uploads the file and inserts a URL pointing at its media host.
4. Leave that URL on its own line so GitHub can render the player. Preview the README before you commit.
5. Commit to the default branch so the video appears on the repository home page.

Do not rely on a relative path to an MP4 checked into the repo as the player source. In practice GitHub renders inline video from files uploaded through the editor (the githubusercontent-style URL it inserts), not from an arbitrary path or a third-party domain. If the player does not appear in preview, re-upload through the editor rather than pasting an external URL.

What are the GitHub README video size limits?#

GitHub documents these caps for media uploads:

• Images and GIFs: 10 MB
• Videos on a free plan: 10 MB
• Videos on a paid plan: 100 MB (with the membership rules GitHub lists for uploads over 10 MB)
• Other file types: 25 MB

Those numbers come from GitHub's attaching-files documentation and can change, so check that page on the day you publish if a limit is load-bearing for your launch. A 30 to 60 second product clip usually fits under 10 MB if you keep the resolution at 1080p, use H.264, and avoid long static holds.

If the file is still too large, cut the runtime, lower the bitrate, or move the full walkthrough to YouTube and keep a shorter clip (or a GIF) on the README.

Should you use a GIF, an MP4 or a YouTube embed?#

Pick one primary format for the top of the README so the page does not fight itself. A common pattern is a 20 to 45 second MP4 under the title, then a text install section, then a link to a longer YouTube walkthrough for people who want depth.

For export settings that work across sites, see product demo video resolution and format. For the YouTube side of a longer cut, see YouTube SEO for product demo videos.

How long should the README demo be?#

Short. The README is a landing page for developers who arrived to evaluate the repo, not a webinar. Show the install or the main happy path, name the product on screen, and stop. A clip that runs past a minute rarely gets finished on a repository page.

If you need a full tour, link out. Keep the README clip as the proof that the product runs, and put the long version on a docs page or YouTube.

How do you keep the README video from going stale?#

Rebuild it when the UI or the main flow changes. A README that shows last quarter's screens loses trust faster than a missing video. Prefer a workflow that regenerates the demo from the current product rather than a one-off screen recording you have to re-shoot by hand.

DemoVexa reads your product's code and rebuilds the screens and voiceover when the app changes, which is useful when the same clip also has to ship on the homepage and social. The code-to-demo overview and the features page cover that path. Solo and Agency pricing are on Pricing if you want the desktop app for that rebuild loop.