Capture X11 Windows and Screen Areas with ImageMagick import

You will finish with a repeatable way to capture one X11 window, the whole screen, or a rectangular area into a normal image file. The examples 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. These commands normally run as your ordinary account. Do not use sudo: root will not fix a missing display connection and can create root-owned output files.

1. Check the installed command and display

Start with read-only checks. The package provides the versioned executable, while import and import-im6 are commonly available 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 include more build details. If DISPLAY is empty, stop here and use the display setup for your desktop, remote X session, or trusted X11 forwarding connection. An unset display is not a reason to guess a server name. The capture examples below cannot work until an X server is reachable.

Checkpoint: confirm that the destination is writable before you begin an interactive capture:

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

2. Capture a single window

With no -window option, import-im6.q16 waits for you to select a visible window. Give the output a suffix so ImageMagick chooses the image format from the filename:

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

Move the pointer over the window and click when the selection cursor appears. The command returns after writing the file. If the selection interface offers a way to cancel, use its documented cancel action rather than killing the terminal blindly.

Do not put untrusted text into the filename without quoting it. The double quotes above protect the destination path, while the date is generated by your 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 ...

Replace the displayed timestamp with the actual filename. The exact dimensions and file wording depend on the selected window.

3. Capture the whole X11 screen

The root window represents the complete X screen. Use -window root to avoid an interactive selection:

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

The dimensions in the verification output are examples, not a promise about your monitor. A multi-monitor X setup may expose one root window spanning more than one physical display. Check the dimensions and inspect the image if the boundary matters.

This command can overwrite an existing file. That is a destructive file operation because the old image is truncated before the new capture completes. Choose a new name, or make an explicit backup first:

$ 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 in place and remove only the incomplete screen-new.png. Once you have checked the replacement, the backup is recoverable until you deliberately delete it.

4. Capture a rectangular area

For an area that is not a complete window, omit -window and select the rectangle interactively. The output format still comes from the suffix:

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

Click and drag over the required rectangle, then release. Keep sensitive windows out of the selection. A screenshot can contain passwords, private messages, access tokens, customer data and other information that is easy to overlook when the image is later attached to a ticket or uploaded to a public service.

For a repeatable rectangle, -crop describes a preferred size and location, but it is not a substitute for understanding which X window is being imported. First make a normal capture and verify its dimensions. If you need a scripted, fixed region, test the exact geometry on a disposable output and inspect it before using it in automation.

5. Select a known window and display

If you already know an X window identifier or name, pass it to -window instead of relying on a pointer selection:

$ 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. Obtain the identifier with a trusted X11 window inspection tool available on your system, then quote it if your shell command constructs it from another value. A window name can also be accepted by the installed ImageMagick build, but names are less reliable when several windows share the same title.

To target a different X server, use -display:

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

Replace SERVER:SCREEN with a value valid for your X setup. Remote display access is security-sensitive: X11 access can expose existing windows and accept input from clients. Prefer an authenticated, trusted forwarding arrangement and do not publish a display socket or disable access controls merely to make a capture work.

6. Diagnose a failed capture

Run the smallest checks first. This shows whether the command exists and whether the display variable is set without changing any files:

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

An error such as "unable to open X server" means the process could not connect to the display named by DISPLAY or -display. Check that the graphical session is running, that the variable belongs to that session, and that your account is authorised to connect. Do not respond by running the capture as root.

If the command exits successfully but the file is missing or empty, inspect the directory and the exact quoted path. If the image opens but has unexpected borders, remember that -border and -frame explicitly alter what is included around a window. If the output format is surprising, use an explicit suffix such as .png, .jpg or .ps; the manual's default is PostScript when no format is otherwise selected.

For more detail during troubleshooting, -verbose reports image information and -debug events produces much more diagnostic output. Avoid leaving verbose debugging enabled in a long-running script, because logs can expose filenames and environment details:

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