How to Convert Images for GitHub READMEs
A well-illustrated README makes the difference between a GitHub repository that attracts contributors and one that gets ignored. Screenshots, architecture diagrams, demo GIFs, and badges help visitors understand what your project does within seconds. But GitHub has specific limitations on image formats, file sizes, and embedding methods that you need to work within.
The most common mistakes are embedding huge screenshots that bloat the repository, using formats that GitHub does not render inline, or hosting images on external services that eventually go offline. Understanding GitHub's image handling helps you create READMEs that look professional and load quickly.
This guide covers the practical details of preparing and embedding images in GitHub repositories.
Step-by-Step Instructions
- Choose the Right Format
GitHub renders PNG, JPG, GIF, and SVG inline in README files. PNG is best for screenshots and diagrams because it preserves sharp text and UI elements. JPG is acceptable for photographs but not ideal for screenshots (compression blurs text). SVG is perfect for diagrams, logos, and badges because it scales to any size. GIF works for short animations and demo recordings.
- Optimize File Size
Every image committed to a Git repository increases the clone and download size permanently (even if deleted later, it remains in Git history). Keep images as small as possible. PNG screenshots should be under 500KB. Compress PNGs with tools that reduce file size without quality loss. JPG screenshots should use quality 80 to 85. SVG files should be cleaned of editor metadata.
- Resize to Reasonable Dimensions
GitHub's README render width is approximately 888 pixels on desktop. Screenshots wider than this are scaled down by the browser, wasting file size. Resize screenshots to 888 pixels wide (or 1776 for retina clarity). Full-screen application screenshots at 2560 pixels wide are overkill for a README and unnecessarily bloat the repository.
- Store Images in the Repository
Create a docs/images or .github/images directory in your repository to organize README images. Commit images alongside your code so they are always available and versioned. Reference them with relative paths in Markdown: . Avoid external hosting services that may go offline and break your README images.
- Embed with Proper Markdown
Use standard Markdown image syntax: . For controlling image size, use HTML img tags:
. Add descriptive alt text for accessibility. For light/dark theme support, use GitHub's theme-aware syntax with the picture element or separate images for each theme.
Format Guide for GitHub Images
PNG is the default choice for README images. Screenshots of terminal output, application UIs, code editors, and web interfaces all look best as PNG because the lossless compression preserves text clarity. Most screenshot tools save as PNG by default, which is convenient. The main downside is file size, so run PNG files through optimization before committing.
SVG is ideal for architecture diagrams, flowcharts, and logos. GitHub renders SVG files inline in README files, and they look crisp at any zoom level. Tools like Mermaid, Draw.io, and Excalidraw can export diagrams as SVG. Be aware that GitHub sanitizes SVG files for security, so embedded scripts and some advanced SVG features will not work.
- PNG: Screenshots, UI mockups, terminal output (lossless, sharp text)
- SVG: Diagrams, flowcharts, logos, badges (scalable, tiny file size)
- JPG: Photographs only (lossy compression blurs text and UI elements)
- GIF: Short demo animations (keep under 10MB, use video links for longer demos)
GitHub Image Size Limits
GitHub renders images up to 10MB in README files, but this does not mean you should use images anywhere near that size. Every byte adds to clone time for everyone who downloads your repository. Target under 200KB per screenshot and under 500KB total for all README images. For repositories with many images, consider a separate documentation site.
For GIF demos, keep them short (under 10 seconds) and optimized (under 5MB). For longer demos, record a video, upload to YouTube or a similar service, and embed a thumbnail image that links to the video. This keeps the repository lean while still providing a visual demo.
Convert Screenshots for GitHub
imageconvert.co converts images to GitHub-ready formats in your browser. Convert WebP screenshots to PNG, optimize photos to JPG, or convert between any supported formats. No upload to any server, which matters when your screenshots contain sensitive information like API keys or internal URLs.
Frequently Asked Questions
What image format is best for GitHub README files?
PNG is best for screenshots and UI images because it preserves sharp text without compression artifacts. SVG is ideal for diagrams, flowcharts, and logos because it scales to any size. Use JPG only for photographs (not screenshots) and GIF for short animations.
How do I add an image to a GitHub README?
Store the image in your repository (e.g., docs/images/screenshot.png) and reference it with Markdown: . For controlling display size, use an HTML img tag: 
.
Why does my GitHub README image not display?
Common causes: the file path is wrong or case-sensitive (GitHub is case-sensitive), the image is hosted externally and the host is blocking GitHub's servers, or the image format is not supported (HEIC, WebP from some sources, and BMP do not display). Verify the path and try PNG or JPG format.
Does GitHub support WebP images in README files?
GitHub has limited WebP support in README rendering. It works in some contexts but not reliably across all GitHub interfaces (web, mobile app, API previews). PNG and JPG are universally supported and recommended for README images.
Convert WebP screenshots to PNG