Capture X11 Windows and Screen Areas with ImageMagick import

import-im6.q16 grabs one X11 window, the whole screen or a rectangle you drag out, and writes it straight to an image file. The examples below target the installed ImageMagick 6 command, import-im6.q16, from package version 8:6.9.12.98+dfsg1-5.2ubuntu0.1~esm14.

Allow about ten minutes for a first capture. You need an active X server, a writable destination directory, and permission to view the display. Run these as your ordinary account: sudo will not fix a missing display connection, and it can leave you with root-owned output files instead.

1. Check the installed command and display

Start read-only. The package supplies the versioned executable, while import and import-im6 are common aliases for the same ImageMagick family:

$ command -v import-im6.q16
/usr/bin/import-im6.q16
$ import-im6.q16 -version
Version: ImageMagick 6.9.12-98 Q16 x86_64
$ printf 'DISPLAY=%s\n' "${DISPLAY-}"
DISPLAY=:0

Your version line may carry more build detail. If DISPLAY comes back empty, stop and sort out display setup for your desktop, remote X session or trusted X11 forwarding connection first: guessing a server name gets you nowhere, and none of the captures below work until an X server is reachable.

$ test -w "$HOME/Pictures" && echo writable
writable

2. Capture a single window

With no -window option, import-im6.q16 waits for you to click a window. Give the output a suffix so ImageMagick can pick the format from the filename:

$ import-im6.q16 "$HOME/Pictures/window-$(date +%Y%m%d-%H%M%S).png"

Move the pointer over the target window and click once the selection cursor appears. The command returns once the file is written. If the selection interface offers a cancel action, use that rather than killing the terminal outright.

Keep untrusted text out of the filename unless it is quoted. Those double quotes above protect the path while the date comes from your own shell. Check the result before opening or sharing it:

$ file "$HOME/Pictures/window-YYYYMMDD-HHMMSS.png"
/home/you/Pictures/window-YYYYMMDD-HHMMSS.png: PNG image data, ...
$ identify "$HOME/Pictures/window-YYYYMMDD-HHMMSS.png"
/home/you/Pictures/window-YYYYMMDD-HHMMSS.png PNG ...

Swap in the real filename for that timestamp placeholder. The exact dimensions and file wording depend on the window you selected.

3. Capture the whole X11 screen

The root window is the whole X screen, and -window root skips the interactive selection:

$ import-im6.q16 -window root "$HOME/Pictures/screen.png"
$ identify "$HOME/Pictures/screen.png"
/home/you/Pictures/screen.png PNG 1920x1080 ...

Those dimensions are an example, not a promise about your monitor. A multi-monitor X setup may present one root window spanning several physical displays, so check the numbers and eyeball the image if the boundary matters.

$ cp --preserve=all "$HOME/Pictures/screen.png" "$HOME/Pictures/screen.png.bak"
$ import-im6.q16 -window root "$HOME/Pictures/screen-new.png"
$ identify "$HOME/Pictures/screen-new.png"
$ mv "$HOME/Pictures/screen-new.png" "$HOME/Pictures/screen.png"

If the new capture fails, leave the original alone and remove only the incomplete screen-new.png. Once the replacement checks out, the backup stays recoverable until you deliberately delete it.

4. Capture a rectangular area

For anything short of a full window, drop -window and drag out the rectangle by hand. The output format still comes from the suffix:

$ import-im6.q16 "$HOME/Pictures/area.png"

For a repeatable rectangle, -crop describes a preferred size and location, but it does not replace knowing which window is actually being captured. Make a normal capture first, check its dimensions, then test the exact geometry on a disposable output before wiring it into automation.

5. Select a known window and display

If you already have an X window identifier or name, pass it to -window instead of clicking:

$ import-im6.q16 -window WINDOW_ID "$HOME/Pictures/known-window.jpg"
$ identify "$HOME/Pictures/known-window.jpg"
/home/you/Pictures/known-window.jpg JPEG ...

WINDOW_ID is a placeholder, not a literal value. Get the real identifier from a trusted X11 window inspection tool, quoting it if your command builds it from another value. This ImageMagick build also accepts a window name, but names get unreliable once several windows share a title.

To target a different X server, use -display:

$ import-im6.q16 -display SERVER:SCREEN -window root "$HOME/Pictures/remote-screen.png"

Swap in a value that is valid for your own X setup. Remote display access is security-sensitive: X11 access can expose existing windows and accept input from clients. Stick to an authenticated, trusted forwarding arrangement, and never open up a display socket or drop access controls just to get a capture working.

6. Diagnose a failed capture

Run the smallest checks first, before touching any files. This confirms the command exists and the display variable is set:

$ command -v import-im6.q16
/usr/bin/import-im6.q16
$ printf 'DISPLAY=%s\n' "${DISPLAY-}"
DISPLAY=:0

• "unable to open X server". The process could not reach the display named by DISPLAY or -display. Check the graphical session is running, the variable belongs to it, and your account is authorised to connect. Do not respond by running the capture as root.
• File missing or empty despite success. Inspect the directory and the exact quoted path.
• Unexpected borders. -border and -frame explicitly add to what is captured around a window.
• Surprising format. Use an explicit suffix such as .png, .jpg or .ps: the manual's default is PostScript when nothing else selects a format.

For more detail while troubleshooting, -verbose reports image information and -debug events gives you a lot more. Do not leave verbose debugging switched on in a long-running script: the logs can expose filenames and environment details.

$ import-im6.q16 -verbose -window root "$HOME/Pictures/debug-screen.png"