GitHub doesn't support embedded video players in README files, but you have three workarounds: drag-and-drop an MP4 file directly into an issue or pull request comment, link a YouTube thumbnail image that clicks through to the video, or upload a GIF as an animated preview. Each method works entirely in the browser with no tools required.
Adding Videos to Your GitHub README — What Works and What Doesn't
A demo video in your README can instantly show visitors what your app does — far more effectively than paragraphs of text. However, GitHub's Markdown renderer doesn't support embedding YouTube or Vimeo players the way a website or blog would. You can't just paste a YouTube embed code and have it play inline. But there are three reliable workarounds that look professional and work entirely in the browser. First, GitHub now supports MP4 video uploads directly in comments and README files — you drag and drop a video file, and GitHub hosts it. Second, you can create a clickable thumbnail image that links to YouTube. Third, you can convert a short clip to a GIF and embed it as an animated image. If you're showcasing an app built with Lovable, V0, or any AI tool, a 30-second screen recording can make your repository stand out and help potential users understand your project at a glance.
Prerequisites
- A GitHub account with a repository
- A video file (MP4, under 10MB) or a YouTube video link
- Basic Markdown knowledge (see our Markdown tutorial)
Step-by-step guide
Upload an MP4 video by dragging it into the README editor
Upload an MP4 video by dragging it into the README editor
Navigate to your repository and click the pencil icon on your README.md file to edit it. Place your cursor where you want the video to appear. Now open a file explorer window and find your MP4 video file (keep it under 10MB — GitHub's upload limit). Drag the video file from your file explorer directly into the GitHub editor's text area. GitHub will show an uploading progress bar and then insert a Markdown link to the hosted video. The syntax it generates will look like: a video tag or a user-attachments link. When rendered, visitors will see a built-in video player with play/pause controls.
Expected result: Your README editor shows an auto-generated link to the uploaded video file.
Create a clickable YouTube thumbnail that links to your video
Create a clickable YouTube thumbnail that links to your video
If your demo video is on YouTube, you can create a professional-looking thumbnail link. First, get your YouTube video ID — it's the part after "v=" in the URL (for example, "dQw4w9WgXcQ" from youtube.com/watch?v=dQw4w9WgXcQ). Then, in your README editor, type this Markdown pattern: [](https://www.youtube.com/watch?v=YOUR_VIDEO_ID). Replace YOUR_VIDEO_ID with your actual video ID. This creates an image (the YouTube thumbnail) wrapped in a link to the video. When someone clicks the thumbnail, they'll be taken to YouTube to watch the full video.
Expected result: The Preview tab shows a YouTube thumbnail image that links to your video.
Upload a GIF as an animated preview of your app
Upload a GIF as an animated preview of your app
GIFs are a lightweight alternative that play automatically in the README without any click required. Record a short screen capture (5-15 seconds) of your app in action, then convert it to a GIF using a free online tool like ezgif.com or the built-in screenshot tools on your computer. Keep the GIF under 5MB for fast loading. In the README editor, drag and drop the GIF file just like you would a video — GitHub will upload it and insert an image tag. Alternatively, type the Markdown manually: . GIFs autoplay and loop, making them perfect for showing quick interactions like clicking a button or navigating between pages.
Expected result: Your README Preview shows an animated GIF that plays automatically.
Add a video section heading and description around your media
Add a video section heading and description around your media
Don't just drop a video or GIF into your README without context. Add a section heading above it using Markdown: "## Demo" or "## How It Works." Below the heading and above the video, write one or two sentences explaining what the viewer will see — for example, "Watch a 30-second walkthrough of the dashboard, including login, data visualization, and export features." This gives context and helps visitors decide whether to watch. After the video, add a link to your live app if it's deployed: "Try it live: [myapp.vercel.app](https://myapp.vercel.app)".
Expected result: Your video is framed with a section heading, a brief description, and a link to the live app.
Commit your changes and verify the video renders correctly
Commit your changes and verify the video renders correctly
Click the "Preview" tab to check that your video, thumbnail, or GIF displays correctly. For MP4 uploads, you should see a video player. For YouTube thumbnails, you should see a clickable image. For GIFs, you should see an animated image. If anything looks broken, switch back to the Edit tab and check your Markdown syntax — the most common issue is a missing bracket or parenthesis in the image/link syntax. Once everything looks good, click "Commit changes," add a commit message like "Add demo video to README," and click the green "Commit changes" button.
Expected result: Your repository's main page shows the README with a visible and functional video, thumbnail, or GIF.
Complete working example
1# My AI-Built App23A modern web app built with Lovable and deployed on Vercel.45## Demo67Watch a quick walkthrough of the app in action:89[](https://www.youtube.com/watch?v=YOUR_VIDEO_ID)1011> Click the image above to watch on YouTube.1213## App Preview14151617*The dashboard updates in real time as new data comes in.*1819## Try It Live2021- [Production App](https://myapp.vercel.app)22- [GitHub Repository](https://github.com/username/repo)2324## Tech Stack2526- React + TypeScript27- Supabase (auth & database)28- Tailwind CSS + shadcn/ui29- Vercel (hosting)Common mistakes when embedding Videos and GIFs in a GitHub README
Why it's a problem: Trying to paste a YouTube embed iframe code into the README
How to avoid: GitHub strips iframe tags for security reasons. Use the clickable thumbnail method instead: [](youtube-url).
Why it's a problem: Uploading a video file that's too large
How to avoid: GitHub limits uploads to about 10MB for most files. Trim your video to 15-30 seconds or compress it using a free tool like HandBrake before uploading.
Why it's a problem: Using a GIF that's over 10MB and loads slowly
How to avoid: Optimize your GIF using ezgif.com's optimizer, reduce the frame rate, or crop it to a smaller area. Aim for under 5MB.
Why it's a problem: Forgetting the exclamation mark in image syntax
How to avoid: Image Markdown starts with . Without the !, GitHub shows a text link instead of an image.
Best practices
- Keep demo videos under 30 seconds — show the most impressive features quickly
- Always add alt text to images and GIFs for accessibility
- Use GIFs for short interactions (button clicks, navigation) and videos for longer walkthroughs
- Compress media files before uploading to keep your repository lightweight
- Add a descriptive caption below each video or GIF explaining what the viewer is seeing
- Include a link to the live app alongside the demo so visitors can try it themselves
- Use the YouTube thumbnail method for polished, high-quality video links
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I have a 2-minute YouTube demo video of my app built with V0. Write me the Markdown code for my GitHub README that shows a clickable YouTube thumbnail, a section heading, a description, and a link to the live app on Vercel.
Frequently asked questions
Can I embed a YouTube video that plays directly in my README?
No. GitHub doesn't support inline video embeds or iframes for security reasons. The best alternative is a clickable thumbnail image that opens YouTube in a new tab when clicked.
What video formats does GitHub support for direct upload?
GitHub supports MP4, MOV, and WebM formats for direct uploads in issues, pull requests, and discussions. MP4 with H.264 encoding is the most universally compatible option.
Is there a file size limit for video uploads on GitHub?
Yes. GitHub allows uploads up to 10MB in the web editor and up to 25MB in issue/PR comments. For larger videos, host them on YouTube and use the thumbnail method.
How do I record a screen capture of my app for the README?
On macOS, press Cmd+Shift+5 to open the screen recorder. On Windows, press Win+G to open the Game Bar recorder. Record a 15-30 second walkthrough of your app's key features, save as MP4, and upload to GitHub.
Can I add demo videos for apps built with AI tools like Lovable?
Absolutely. If your app is deployed via Lovable's Publish feature, open the published URL, record a screen capture, and upload it to your README. This is one of the best ways to showcase what your AI-built app can do. If you need help creating professional demos, RapidDev can help you put together polished project documentation.
Do GIFs autoplay in GitHub READMEs?
Yes. GIFs embedded in a GitHub README will autoplay and loop automatically when a visitor views the page. There's no play button needed — the animation starts immediately.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation