DevelopersSupportBug reportsRedactmacOS

How to Take a Good Bug Report Screenshot on Mac

Name: Pizazoo
Author: Pizazoo

Capture the right window, annotate the steps, cover tokens and customer data with solid boxes, and name files so a bug report screenshot gets fixed fast.

October 6, 20266 min read

Muhammed BasilFounder & maker of Pizazoo

A good bug report screenshot shows the problem in context (the whole window, the URL or app version, and when it happened), points at the exact spot with an arrow or numbered steps, and hides secrets and customer data under solid boxes before anyone else sees it. On a Mac, press Shift-Command-4 then Space to capture one window, mark it up in Markup or Preview, and switch to a screen recording when the bug only shows up across several steps. The steps below apply to macOS Tahoe 26 and macOS 27.

We make Pizazoo, a screenshot organizer for Mac and iPhone. It comes up in one section near the end; every built-in method here works without it.

What should a bug report screenshot include?

Whoever picks up the ticket should be able to reproduce the problem without asking you anything. Mozilla's guide to filing good bugs asks for steps to reproduce and "things such as operating system and version" (Firefox Source Docs). A screenshot can carry much of that:

The whole window, not only the error text. A tight crop of a red message loses the page and the state that explains how you got there.
Where it happened. Keep the address bar in frame for web bugs. For the OS version, choose Apple menu > About This Mac (Apple); on iPhone, go to Settings > General > About (Apple).
Which environment and account. Staging or production, which test user. If it isn't on screen, write it in the ticket.
When it happened. macOS names each screenshot with the date and time it was taken (Apple), which helps line it up with server logs.
The console, for web bugs. In Safari, choose Safari > Settings, click Advanced, then select "Show features for web developers" (Apple), open Web Inspector from the Develop menu and capture its Console, which lists the page's logs, errors and warnings (Apple Developer). In Chrome, Command-Option-J opens the Console (Chrome for Developers).

Paste error messages and stack traces as text too. Text can be searched and copied; pixels can't.

Should you capture the full window or a selected region?

Default to a single window. It shows enough context without your other apps, notification banners or private tabs.

What you need	Shortcut	Tip
One window	Shift-Command-4, then Space, then click the window	Hold Option as you click to leave out the window's shadow
Part of the screen	Shift-Command-4, then drag	Hold Space while dragging to move the selection without resizing it
The entire screen	Shift-Command-3	Includes the menu bar and everything else that's open
An open menu	Open the menu, press Shift-Command-4, drag over it	Good for wrong or missing menu items
Straight to the clipboard	Add Control to any shortcut above	Paste directly into the ticket

These shortcuts come from Apple's screenshot article and the Mac User Guide. Shift-Command-5 opens the Screenshot app, whose Options menu adds a Timer for hover states and tooltips, Show Mouse Pointer, and Remember Last Selection for before-and-after shots of the same area.

How do you annotate a screenshot for a bug report?

Click the floating thumbnail right after you take the screenshot to open a window where you can mark it up, or open the file in Preview and show the Markup toolbar (Apple). The built-in tools cover the basics: Shapes (lines, arrows, rectangles and more, plus a Highlight shape and a Loupe that magnifies an area), Text, and border and fill colors (Apple: Mark up files on Mac).

A few rules keep annotations useful:

One arrow or box per problem, in a color that stands out. Never cover the broken thing itself.
For a sequence, number the steps. Markup has no step counter, so add text boxes with 1, 2 and 3 beside each click target.
Write expected versus actual behavior in the ticket, not only on the image.

How do you hide secrets and customer data before sharing?

Scan for anything you wouldn't paste into a public channel: API keys, access tokens, session cookies and authorization headers (developer tools are full of them), passwords, customer names, emails, phone numbers, account IDs, internal hostnames and QR codes. Check notification banners too.

Cover them with an opaque, filled rectangle, not blur or pixelation:

Security firm Bishop Fox says "the only way to do it securely is to use black bars," and built Unredacter to turn pixelated text back into readable text (Bishop Fox).
Depix is a proof of concept "to recover plaintext from pixelized screenshots" (Depix).
A 2016 paper showed neural networks recovering information from pixelated and blurred images (McPherson, Shokri and Shmatikov).

In Markup, draw a rectangle and set its border and fill colors to black. Then send a flattened file: Apple notes that once you save an annotated image in Preview, the annotations can't be edited, moved or deleted (Apple). Editors haven't always got this right; in 2023 a flaw nicknamed aCropalypse in Google Pixel's Markup app left cropped-out areas recoverable (The Register). On iPhone, leave All Photos Data off in the share sheet's Options, because it shares "the original file with edit history and metadata" (Apple).

What's visible matters far more than hidden file data (see do screenshots have metadata?). More in how to redact screenshots on Mac and how to blur a QR code in a screenshot.

Should you attach the screenshot or paste it inline?

Paste when speed matters: add Control to any screenshot shortcut to copy the image instead of saving a file (Apple). On GitHub, for example, you can paste images straight into an issue in many browsers, and the file uploads immediately (GitHub Docs). Check two things first:

Who can see it. GitHub says that for public repositories, "uploaded files can be accessed without authentication." Redact before you paste, not after.
Size limits. GitHub caps images at 10MB, and videos at 10MB on free plans (100MB on paid plans).

Attach a saved file when you want a local copy filed under the ticket number, or when you're adding logs: GitHub also accepts .log, .txt and .json files.

How should you name bug report screenshots?

The default name ("Screenshot" followed by the date and time) is good for matching logs but hopeless for finding the file later. A pattern that sorts well and stays searchable is ticket ID, a short description, then the date, for example PAY-142-checkout-500-error-2026-10-06.png. Finder can rename a whole batch at once; see how to rename screenshots on Mac.

When is a screen recording better than a screenshot?

When the bug lives in the sequence: a flicker, a drag that drops in the wrong place, a step that fails only the third time. Press Shift-Command-5 and choose Record Entire Screen, Record Selected Window (macOS Tahoe 26 or later) or Record Selected Portion (Apple). In Options, choose Show Mouse Clicks; macOS 27 adds Include System Audio. Stop with the menu bar Stop button or Command-Control-Esc.

On iPhone, tap the Screen Recording control in Control Center and wait for the three-second countdown (Apple). Pair any recording with a still screenshot of the final broken state, which is faster to scan.

How does Pizazoo help with bug report screenshots?

We make Pizazoo. It's a Mac app (macOS 14 Sonoma or later) that watches the folders your screenshots land in, from Shift-Command-3, 4 or 5 or apps like CleanShot X, Shottr and Xnapper, and copies each one into a searchable library:

Annotate and redact in one editor. Arrows, shapes, text, numbered steps, spotlight and a magnifier, plus redact, blur and pixelate. Auto-redaction finds personal info and QR codes; review what it caught, and box out tokens and keys yourself.
Find the earlier screenshot. On-device text recognition makes every capture searchable, so searching an error message brings up the screenshot from the first time it happened. Captures are sorted into categories such as Errors and Code.
Keep it local. Text recognition and categorization run on your Mac, with no Pizazoo server and no account.

The iPhone and iPad app has a markup editor with arrows, numbered steps and blur or black out for mobile QA. See Pizazoo for developers and Pizazoo for support teams, or download Pizazoo.