How to Add Screenshots to a GitHub README

To add a screenshot to a GitHub README, save it as an image file inside the repository (for example docs/images/settings.png), reference it with a relative path such as ![Settings window](docs/images/settings.png), and commit the image together with the README change. GitHub recommends relative links for images that live in the repository, because they keep working on every branch and in every clone. Dragging an image into a GitHub comment box also works, but it uploads the file to GitHub's attachment storage instead of your repository.

Step by step on Windows

1. Capture the screenshot. Press Windows logo key + Shift + S and select an area. On Windows 11, Snipping Tool saves each capture to your Screenshots folder automatically, and the image is also on the clipboard. What Win+Shift+S actually saves covers the details if your captures aren't where you expect.
2. Put the file in the repo. Create a folder such as docs/images/ and save or move the image there. Give it a name that says what it shows, like settings-window.png, not Screenshot 2026-08-21 101512.png.
3. Add the Markdown. In README.md, write !Settings window with the Dark theme selected](docs/images/settings-window.png). The text in the brackets is the alt text that screen readers announce and that shows if the image fails to load. If a designer supplied the image, [keep its alt text with it through the handoff rather than rewriting it here.
4. Preview it. In VS Code, press Ctrl+Shift+V in the Markdown file to open the preview and check the image loads.
5. Commit both files in one commit. git add README.md docs/images/settings-window.png, then commit. If you commit the README first, it points at a file that doesn't exist in that revision.

The fastest route: paste the snip into VS Code

VS Code can do steps 2 and 3 for you. Take the snip with Win+Shift+S, open README.md, and press Ctrl+V. VS Code saves the clipboard image as a file in your workspace and inserts the ![](path) link at the cursor. You can also drag an image file from File Explorer into the editor; hold Shift to drop it into the file.

To control where pasted images go, set markdown.copyFiles.destination in your settings. It maps Markdown files (by glob) to a destination folder:

"markdown.copyFiles.destination": {
    "/README.md": "docs/images/"
}

After pasting, rename the new file to something descriptive and fill in the alt text, which VS Code leaves empty.

How relative image paths work on GitHub

A relative path is resolved from the Markdown file that contains it, not from the repository root:

Three habits avoid broken images:

• Match the case exactly. GitHub paths are case-sensitive, so Settings.PNG and settings.png are different files even though Windows treats them as the same.
• Use forward slashes. Write docs/images/app.png, never docs\images\app.png.
• Never link a local path. A link to C:\Users\... works only on your machine and breaks for everyone else.

Uploading through GitHub instead

You can also drag an image into, or paste it into, the comment box of an issue, pull request or discussion. GitHub uploads it and inserts a link to the stored file. Images and GIFs can be up to 10 MB; supported image types are PNG, GIF, JPEG and SVG, and videos can be MP4, MOV or WebM.

That's the right tool for a one-off bug report or a review comment. For a README it has trade-offs:

• The image isn't part of the repository, so it doesn't appear in clones or in Markdown previews that work offline.
• Visibility follows the repository. In a public repo, uploaded files can be opened without signing in; in a private repo, only people with access can view them.
• Changing the screenshot means uploading again and editing the link, with no history of the old image in your commits.

Some people upload through an issue comment just to get a link, then paste that link into the README. It works, but the file in the repo is the more durable choice.

Which screenshots belong in git

Put the image in the repository when it documents how the code behaves now or something depends on it:

• README and documentation figures,
• images your app or website ships (src/assets/...),
• visual-regression baselines that tests compare against,
• before-and-after pairs a future reviewer needs to reopen.

Keep it out of the repository when it's evidence for a single moment, such as a crash dialog for one bug. Attach that to the issue; how QA testers stage repro data and screenshots shows a tidy way to collect it. And never commit a screenshot that shows tokens, customer data or internal URLs; crop or recapture it with dummy data first.

Clipboard history is not a substitute for either. Win+V keeps a short list of recent copies on your PC only, and unpinned items are cleared when you restart. CI jobs and teammates can't see it.

Keeping the repository small

Every version of every image stays in git history, so a few habits pay off:

• Crop to what matters. A screenshot of one dialog is smaller and more readable than a full 4K desktop.
• Use PNG for UI. It's lossless, so text stays sharp. JPEG compression smudges text; keep it for photos.
• Replace, don't pile up. Overwrite settings-window.png when the UI changes instead of adding settings-window-v2.png, so links stay the same and history shows the change.

If a repository holds many large images, such as visual-regression baselines, Git LFS stores the file contents outside the normal git object database and commits small pointer files instead. Run git lfs install once, then git lfs track "*.png", and commit the .gitattributes file it writes. Hosts apply their own storage and bandwidth quotas to LFS, so check yours before moving a large image set.

Moving several screenshots at once

When you're redoing documentation, you often take five or six captures in a row. Snipping Tool's automatic saving means they're all in the Screenshots folder, so sort by date and move the new ones into docs/images/. If a capture went only to the clipboard, open Win+V, paste it into Paint and save it as PNG; turning a copied image into a named asset walks through that.

Edge Drop keeps each copied screenshot as an image card on a screen-edge shelf, and dragging a card into a folder in File Explorer drops it there as a PNG file. That's handy for moving a burst of captures into docs/images/ without hunting through folders. How to drag an item out of Edge Drop into any app shows how.

FAQ

Why does my README image show as a broken link on GitHub?

Usually the path is wrong relative to the Markdown file, the letter case doesn't match, or the image was never committed. Open the image path in the repository file browser to check it exists exactly as written.

Can I resize an image in a GitHub README?

Markdown image syntax has no size option. Crop or scale the file itself before committing, so the README stays plain Markdown.

Should README screenshots go in the root or a docs folder?

Either works, as long as the paths match. A dedicated folder such as docs/images/ keeps the root tidy and gives every Markdown file in the repo one place to link to.

Related reading

• Print Screen vs Win+Shift+S vs Snipping Tool (Windows 11)
• How to Save a Copied Image With Your Own File Name
• Where Do Win+Shift+S Screenshots Go? Why They Don't Save
• QA Bug Reports: Stage Repro Steps, Logs, and Screenshots

Sources

• Basic writing and formatting syntax (GitHub Docs) — image syntax, alt text, and how relative links resolve.
• Attaching files (GitHub Docs) — uploading images to comments, size limits, file types and visibility.
• Markdown and Visual Studio Code (VS Code docs) — pasting and dropping images, and markdown.copyFiles.destination.
• Use Snipping Tool to capture screenshots (Microsoft Support) — Win+Shift+S and automatic saving to the Screenshots folder.
• Git Large File Storage — git lfs install and git lfs track for large binary files.

Copy. Stack. Drop.

Transform your clipboard into an interactive edge shelf. Stack, pin, and drag assets into any app with zero friction.

Download for Windows Get from Microsoft Store

How to Install Guide · First 10 Minutes Guide · Drag & Drop Guide · Edge Drop vs Win+V · Support