Screenshot won't paste into Codex CLI? Fixes that work

If a screenshot won't paste into Codex CLI, try Ctrl+V instead of Cmd+V on a Mac, and if that fails, start Codex with codex --image and the screenshot's file path, which works in every terminal.

Updated 2 November 2026

OpenAI's docs give two ways to show Codex a picture: pass it with codex --image when you start, or paste it into the interactive composer. Paste is the one that breaks, and the reason is usually the terminal, not Codex. Here is what works on each setup, checked against the docs and open issues on the Codex repo.

The fix that always works: --image

Save the screenshot as a PNG. On a Mac, Cmd+Shift+4 saves a file to your desktop.
Move it into your project folder, so the path is short.
Start Codex with the picture and your note:

codex --image screenshots/cart.png "On /cart the total stays at $20 when I change the quantity to 3. Expected: $60."

No clipboard is involved, so none of the paste problems below can stop it.

macOS

Use Ctrl+V, not Cmd+V. Terminals send text on Cmd+V, so the picture never arrives. In the Codex issues about this, Ctrl+V is the key that works.
Copy the screenshot, don't just save it. Cmd+Ctrl+Shift+4 puts it on the clipboard. Plain Cmd+Shift+4 only saves a file.
Look for the chip. When it works, an [Image #1] chip shows in the composer before you send. No chip means no picture.

Linux

On Wayland, Ctrl+V may do nothing. An open issue reports this with kitty and Alacritty, with no error shown. Reporters say dragging the file into the terminal works.
Check your terminal config. In the same issue, one person's Alacritty key settings were the cause.
Use --image if neither works.

The path trick

Paste or type the full path of an image file into the composer. Codex turns a path to an existing image into an [Image #1] attachment, so you get the picture without the clipboard. If you wanted the path as plain text, put a word in front of it.

Skip the paste step with Darnly

Every fix above ends with a file Codex can read. Darnly makes that file for you. It's a free Chrome extension, and a free Mac app for things outside the browser.

Press Option+Shift+B (Windows is coming soon), click the broken part, and type what you expected. With your project folder linked, Darnly saves a PNG with the broken part boxed in red into .darnly/inbox/, next to a short report with the element, the page address and recent errors. Then tell Codex "fix my bugs". It reads the files from the folder. No clipboard, no key to remember.

For what to write next to the picture, see how to give Codex a screenshot of a bug. Using Claude Code or Cursor? See screenshot won't paste into Claude Code or Cursor.

Questions

Why does Cmd+V not paste a screenshot into Codex CLI on my Mac?

Most terminals only pass text to Cmd+V, so the picture never reaches Codex. In GitHub issues on the Codex repo, the working key on macOS is Ctrl+V. If that fails too, start Codex with codex --image and the file path.

How do I attach a screenshot to Codex CLI from a file?

Start Codex with codex --image path/to/shot.png and your prompt. OpenAI's Codex CLI docs show --image for passing a screenshot with your first prompt.

Ctrl+V does nothing for images on Linux. What now?

An open issue reports that on Wayland, with terminals like kitty and Alacritty, Ctrl+V attaches nothing and shows no error. Reporters say dragging the image file into the terminal works. Or use codex --image.

I pasted a file path and it turned into [Image #1]. Why?

Codex turns a pasted path to an existing image into an image attachment. That is handy when you want the picture. If you wanted the path as text, put a word before it, like "Image file path:".

Does the Codex IDE extension paste images more reliably?

Commenters on the macOS paste issue point to the IDE extension as a place where pasting images works. If the terminal keeps failing, try the extension or use a file.