How to Embed Images in a GitHub README
September 29, 2026 · GetImgURL
A great README with screenshots gets more stars, more contributors, and fewer confused users. But to embed images in a GitHub README, you need one thing first: a public URL for each image. This guide shows you how to get that URL and write the Markdown that displays your images perfectly.
The Markdown Image Syntax
GitHub READMEs are written in Markdown, and embedding an image takes one line:
That is the entire syntax: an exclamation mark, the alt text in square brackets, and the image URL in parentheses. GitHub renders it as the actual image when anyone views your repo.
Example in a real README:
## Demo
Upload any JPG, PNG, or GIF and get a shareable link in seconds.
Step 1: Get a Hosted Image URL
Markdown cannot display an image from your hard drive — the file must live at a public URL. The quickest way to get one is GetImgURL's free image to URL tool:
- Take your screenshot or export your graphic (PNG works best for UI captures).
- Open the Photo to URL converter.
- Drag and drop the image — or paste it straight from your clipboard with Ctrl+V (Windows) or Cmd+V (Mac).
- Copy the direct link (or the Markdown snippet, which is pre-formatted for you).
The tool accepts JPG, PNG, WEBP, and GIF up to 10MB, needs no signup, and gives you the URL in seconds. If your screenshot is oversized, trim it first with the free resize image tool — README images rarely need to be wider than 800–1000px.
Step 2: Add the Image to Your README
Open your repo's README.md and paste the Markdown where you want the image to appear:
Commit and push. GitHub renders the image inline automatically — no plugins, no configuration.
Centering an image
Markdown has no native centering, but GitHub renders inline HTML, so this works:
<p align="center">
<img src="https://your-image-link.png" alt="Upload page screenshot" width="700">
</p>
Controlling image size
Markdown syntax cannot set dimensions, but the HTML <img> tag can:
<img src="https://your-image-link.png" alt="Demo screenshot" width="600">
Use this for large screenshots that would otherwise stretch the full width of the page. (For more on crafting <img> tags, see our guide to getting an image URL for HTML.)
Relative vs. Absolute Image Paths
You have two options for README images, and it is worth knowing the trade-off:
| Approach | Example | Pros | Cons |
|---|---|---|---|
| Absolute URL |  | Works everywhere the README is viewed — GitHub, npm, package mirrors | Depends on the image host |
| Relative path |  | Image lives in your repo, versioned with your code | Bloats the repo; won't render on npm if the file isn't published |
Our recommendation: use absolute URLs from a dedicated image host for screenshots and demos. It keeps your repository lean — no binary files inflating every clone — and the same URL works if your README is mirrored on npm or another registry. Commit the image to the repo only if it must stay in lockstep with the code (like architecture diagrams tied to a specific release).
Tips for README Images That Look Professional
- Use PNG for screenshots. Text stays crisp; JPG artifacts make UI captures look blurry.
- Keep widths reasonable. 800px is plenty for most screenshots. Resize larger captures before uploading.
- Compress before uploading. Smaller files load faster for everyone viewing your repo — run images through the compress image tool first.
- Write meaningful alt text. It helps visually impaired users and shows if the image ever fails to load.
- Show, don't tell. A 3-step annotated screenshot beats three paragraphs of setup instructions.
Showcasing Multiple Images
Many READMEs need more than one screenshot. Two clean patterns handle that:
Side-by-side with a table. GitHub renders Markdown tables, and images inside table cells sit next to each other:
| Before | After |
| ------ | ----- |
|  |  |
A feature gallery. Stack labeled screenshots under H3 headings so readers can scan quickly:
### Upload
### Copy link
Keep each image under 800px wide — resize larger captures with the resize image tool before uploading — so galleries load fast and look tidy on every screen size.
Frequently Asked Questions
How do I embed images in a GitHub README without uploading to the repo?
Host the image with a free tool like GetImgURL's image to URL converter, copy the direct link, and reference it with  Markdown. Nothing gets committed to your repository.
Why is my README image not showing on GitHub?
Check three things: the URL must be public (open it in a private window), it must point directly to the image file (not a preview page), and the Markdown syntax needs the leading ! — [text](url) without it renders as a text link.
Can I resize an image in GitHub README Markdown?
Plain Markdown cannot resize, but GitHub supports inline HTML: <img src="URL" width="600">. That is the standard workaround.
What is the best image format for GitHub README screenshots?
PNG for anything with text or UI elements (stays sharp), JPG for photographs, GIF for short animated demos. Convert between formats with the free image converter if needed.
Make Your README Visual Today
Screenshots sell your project better than paragraphs ever will. Upload your first capture to the free Photo to URL converter, paste the Markdown into your README, and watch your repo look instantly more professional.
Try it right now — free, no sign-up
Upload an image and get a shareable link in seconds.
Convert image to URL
