How to attach a screenshot to a bug report on a Mac

Capture the problem with Shift-Command-4, mark it up in the preview that appears, then drag the file into the bug report or paste it with Command-V. Which of the two works depends on the form, so it helps to know both and to keep the screenshot where you can find it until it is sent.

Capture the right thing

A good bug screenshot shows the problem and enough context to place it. Too tight and nobody knows which screen it came from; too wide and the error is lost.

• A region. Press Shift-Command-4, then drag a box around the area. Release to capture.
• A single window. Press Shift-Command-4, then Space. The pointer becomes a camera; click the window to capture it with its title bar.
• The whole screen. Press Shift-Command-3.
• The options panel. Press Shift-Command-5 for a toolbar with all of these, plus screen recording and a timer. Click Options to choose where captures are saved.

If the problem is a menu that closes when you click away, use the timer in the Shift-Command-5 panel, open the menu during the countdown, and let it capture.

For anything that moves, such as a glitch that flickers or a button that does nothing, a short screen recording from the same panel explains more than a still image. The file lands in the same place as screenshots, and most ticket systems accept it.

Mark it up before you attach it

After you capture, a thumbnail appears in the corner of the screen for a few seconds. Click it to open Markup, where you can:

1. Draw a rectangle or arrow around the faulty part. Choose the shape button in the toolbar.
2. Add a text note such as “Button stays gray after saving”.
3. Crop the edges with the crop tool so the image carries only what matters.
4. Click Done to save the changes.

If the thumbnail has already disappeared, find the file on the desktop (screenshots go there by default), select it, and press the Space bar for Quick Look. The Markup button is in the Quick Look toolbar.

Look out for private details

A screenshot of a bug report is usually shared with other people, and often with a vendor or a public tracker. Before it goes anywhere, look at the whole image:

• Email addresses and names in the corner of the window.
• Notification banners that slid in during the capture.
• Address bars, tokens or keys visible in a settings page.
• Other open windows behind the one you meant to show.

Use the Markup tools to draw a solid filled rectangle over anything sensitive, and then save. Be aware that Markup shapes can sometimes be edited later in the same file, so for truly private details, crop them out instead of covering them.

Get it into the report

Where the screenshot goes decides how you move it.

A form with an upload button. Click the button and pick the file from the dialog. Screenshots are on the desktop unless you changed the location. Getting a file into a web upload field fast lists quicker ways in.

A comment box that takes pasted images. Many ticket pages accept a pasted image. To copy a screenshot straight to the clipboard without saving a file, add Control to the shortcut: Control-Shift-Command-4. Then click in the comment box and press Command-V. If nothing happens, the box does not take pasted images and wants a file instead.

A comment box that takes dragged files. Drag the file from the desktop onto the box. You will usually see it highlight when it is ready for the drop.

Email. Drag the file into the message body or onto the attach button. How to attach a file to an email in one drag explains the details.

A chat message. Drag the file into the message box, or paste the image. Pasting an image sends a picture, while dragging a file sends the file; both are fine for a bug.

Keep the image handy while you fill in the form

Bug forms are fussy. You often need to write a description, switch to another window to check a version number, then come back and attach the picture. The screenshot sits on the desktop behind your windows, and getting to it means hiding everything.

Ledge is a good fit for that gap. Drag the screenshot (or its thumbnail from the corner) up to the notch and let go. It lands on a shelf that stays there until you take it somewhere. When you reach the attach step in the browser, press Option-Space to open the shelf and drag the image onto the upload area or the comment box. The format-aware hand-off means a browser upload field gets the file and a terminal gets the path as text, so the same shelf item works for a bug report and for a command-line tool that asks for an image path. Ledge needs macOS 14 Sonoma or later, and it never sends your screenshots anywhere: there is no account and no cloud. For another example of the habit, see how to stage screenshots before posting them.

Include the words that make the picture useful

An image alone rarely explains a bug. Pair it with three short lines in the report:

1. What you did, step by step.
2. What you expected to happen.
3. What happened instead, and the version of the app and macOS. To find the macOS version, choose Apple menu > About This Mac.

A screenshot then confirms the story instead of having to carry all of it.

Questions

Where do screenshots go by default?

On the desktop, named Screenshot followed by the date and time. You can change the folder in the Shift-Command-5 panel under Options.

Why is my screenshot a .png and the form wants a .jpg?

Some forms accept only certain types. Open the file in Preview, choose File > Export, pick JPEG as the format, and save a copy.

Can I attach a recording instead?

Usually yes, but check the size limit first. Select the file and press Command-I to see its size, and trim it in QuickTime Player if it is too long.