How to Add Screenshots to GitHub Pull Requests, Issues, and READMEs on Mac

Why screenshots in pull requests get your PRs reviewed faster

A pull request that changes UI without showing what changed is asking reviewers to check out the branch, run the app, and look for themselves. Most reviewers won't. They'll skim the code diff, approve it, and move on. If your UI change has a subtle layout bug, nobody catches it until QA or production.

Adding a screenshot to your PR description changes the review dynamic entirely. The reviewer sees exactly what you built. They can spot misaligned padding, wrong colors, missing hover states, and layout issues without leaving the GitHub page. Before/after screenshots are even better — they show intent and make it obvious what changed and what didn't.

Teams that require screenshots in UI pull requests consistently report fewer visual bugs reaching production. It takes 10 seconds to capture and paste a screenshot. It takes 30 minutes to debug a layout issue that shipped because nobody looked.

How to add a screenshot to a GitHub PR or issue

GitHub gives you three ways to embed images in PRs, issues, and comments. All three work on Mac.

Method 1: Drag and drop (easiest)

Take a screenshot with Cmd+Shift+4 (region) or Cmd+Shift+5 (options bar). The screenshot saves to your Desktop by default. Open your PR on GitHub, and drag the screenshot file from Finder directly into the description or comment text box. GitHub uploads it and inserts the Markdown image syntax automatically.

Method 2: Paste from clipboard (fastest)

Take a screenshot to clipboard with Cmd+Ctrl+Shift+4 (region to clipboard) or Cmd+Ctrl+Shift+3 (full screen to clipboard). Click into the GitHub text editor and press Cmd+V. GitHub uploads the clipboard image and inserts it inline. No file saved to your Desktop, no drag-and-drop needed.

This is the fastest method: screenshot, switch to GitHub, paste. Three actions, under 5 seconds.

Method 3: Markdown image syntax (for README files)

For README files and wiki pages, you'll use Markdown image syntax since you're editing a file, not a comment:

![Screenshot of the dashboard](screenshot-dashboard.png)

The image file needs to be either committed to the repository or hosted externally. More on the best approach for README screenshots below.

GitHub image format and size requirements

Not every format works on GitHub. Here's what's supported:

Size limits: GitHub accepts images up to 10MB via drag-and-drop or clipboard paste. For images committed to a repo (README screenshots), there's no hard limit, but keep files under 1MB to avoid slow clones and page loads. Retina Mac screenshots are typically 2–5MB at full resolution — you'll want to resize them.

Resizing Retina screenshots for GitHub

Mac Retina displays capture screenshots at 2x resolution. A screenshot of a 1440px-wide browser window produces a 2880px-wide image. In a GitHub PR, this renders at native resolution, which means it overflows the comment width or gets scaled down with browser interpolation, making text slightly fuzzy.

The sweet spot for GitHub screenshots is 1200–1600px wide. GitHub's comment area is about 900px wide, so a 1400px image looks sharp on both regular and Retina displays when GitHub scales it to fit.

Quick resize with sips

sips --resampleWidth 1400 screenshot.png

This resizes in place. To keep the original, add --out resized.png.

Quick resize with Preview

Open the screenshot in Preview. Go to Tools > Adjust Size. Set the width to 1400 pixels (height adjusts proportionally). Save.

Batch resize for multiple screenshots

for f in *.png; do sips --resampleWidth 1400 "$f" --out "resized-$f"; done

Before/after screenshots for UI pull requests

Before/after comparisons are the most effective way to show UI changes in a PR. Here are two Markdown patterns that work well:

Pattern 1: Side-by-side table

| Before | After |
|--------|-------|
| ![before](before.png) | ![after](after.png) |

This renders as a two-column table with images side by side. It works best when the screenshots are narrow enough to fit in half the comment width (under 700px each).

Pattern 2: Stacked with headers

### Before
![before](before.png)

### After
![after](after.png)

This stacks the images vertically with clear labels. Better for wide screenshots where side-by-side wouldn't fit.

Pattern 3: Collapsible details (for large screenshots)

<details>
<summary>Screenshots (before/after)</summary>

### Before
![before](before.png)

### After
![after](after.png)

</details>

This hides the screenshots behind a clickable toggle. Use it when your PR has many screenshots that would make the description too long, or when the screenshots are supplementary to the main description.

Tips for better before/after captures

Same viewport size. Before you start coding, take the "before" screenshot. After your changes, take the "after" screenshot at the exact same browser width and scroll position. Use Cmd+Shift+4 to select the same region, or use Chrome DevTools device mode to lock the viewport width.

Same data. Use the same test data in both screenshots. If the "before" shows a list with 3 items and the "after" shows 7 items, the reviewer won't know if the extra items are part of your change or just different data.

Crop to the change. Don't screenshot the entire page if you only changed the header. Crop tightly to the area that changed, with just enough context to orient the reviewer.

Adding screenshots to your GitHub README

README screenshots are different from PR screenshots. PR images are uploaded to GitHub's CDN automatically. README images need to be either committed to the repo or hosted externally.

Option 1: Commit images to the repo (simplest)

Create a folder in your repo for screenshots:

mkdir -p docs/screenshots
cp screenshot.png docs/screenshots/

Reference them in your README with a relative path:

![Dashboard overview](docs/screenshots/dashboard.png)

Pros: Simple, images stay with the code, no external dependencies.
Cons: Images bloat the repo size. Every version of every screenshot is stored in Git history forever. A repo with 20MB of screenshots adds 20MB to every clone.

Option 2: Upload via a GitHub issue (recommended)

This is the best approach for most projects. Open any issue or PR in your repo, drag your screenshot into the comment box, and copy the generated URL (it looks like https://github.com/user-attachments/assets/...). You don't need to submit the comment — just copy the URL. Use that URL in your README:

![Dashboard overview](https://github.com/user-attachments/assets/abc123...)

Pros: No repo bloat, images served from GitHub's CDN (fast), images persist even if the issue is deleted.
Cons: Images aren't versioned with the code. If GitHub changes their CDN URLs (unlikely but possible), links could break.

Option 3: Use Git LFS for large image sets

If your project requires many committed screenshots (e.g., documentation sites, design systems), use Git Large File Storage:

brew install git-lfs
git lfs install
git lfs track "*.png"
git add .gitattributes
git add docs/screenshots/*.png
git commit -m "Add screenshots via LFS"

Git LFS stores the actual image files on a separate server and only keeps lightweight pointers in your repo. Clones stay fast, and GitHub renders LFS-tracked images normally in the README.

Making your README screenshots stand out

The README is often the first thing someone sees when they visit your project. Polished screenshots make the difference between a project that looks professional and one that looks like a weekend experiment.

Add a background. Raw screenshots on a white GitHub background look flat. Adding a subtle gradient background, rounded corners, and a shadow makes the screenshot pop and gives it visual weight. This is especially important for dark-mode screenshots, which disappear into GitHub's dark theme without a contrasting background.

Show the golden path. Your first README screenshot should show your project doing the thing people came for. Not the settings page. Not the login screen. The main feature, populated with realistic-looking data.

Keep it current. Stale README screenshots — showing an old UI, outdated branding, or removed features — erode trust. Update screenshots when you ship significant UI changes. A quick way to keep them fresh: add a "Update README screenshots" task to your release checklist.

Optimize file size. Resize Retina screenshots to 1400px wide and compress PNGs before committing. A 5MB hero image in your README means visitors on slow connections stare at a broken image placeholder for seconds.

# Resize and compress in one step
sips --resampleWidth 1400 screenshot.png
# Optional: further compress with ImageOptim CLI
imageoptim screenshot.png

Screenshot workflow for GitHub: putting it all together

Here's the workflow that takes the least time and produces the best results:

For PR screenshots:

1. Before coding, take a "before" screenshot to clipboard (Cmd+Ctrl+Shift+4)
2. Paste it into a text file or keep it in clipboard history
3. After coding, take the "after" screenshot at the same viewport size
4. In your PR description, paste both screenshots using the side-by-side table pattern
5. Add a one-line description of what changed above the screenshots

For README screenshots:

1. Capture the screenshot at a consistent viewport width (1440px is a good standard)
2. Resize to 1400px wide with sips
3. Add a background and rounded corners for a polished look
4. Upload via a GitHub issue to get a CDN URL
5. Reference the URL in your README

For issue bug reports:

1. Capture the screenshot showing the bug — annotate it with an arrow or circle pointing to the problem area
2. Include the URL, browser, and viewport size in the issue description
3. Paste the screenshot directly into the issue with Cmd+V