The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.


Imager::Screenshot - screenshot to an Imager image


  use Imager::Screenshot 'screenshot';

  # whole screen
  my $img = screenshot();

  # Win32 window
  my $img2 = screenshot(hwnd => $hwnd);

  # X11 window
  my $img3 = screenshot(display => $display, id => $window_id);

  # X11 tools
  my $display = Imager::Screenshot::x11_open();

  # test for win32 support
  if (Imager::Screenshot->have_win32) { ... }

  # test for x11 support
  if (Imager::Screenshot->have_x11) { ... }


Imager::Screenshot captures either a desktop or a specified window and returns the result as an Imager image.

Currently the image is always returned as a 24-bit image.

screenshot hwnd => window handle
screenshot hwnd => window handle, decor => <capture decorations>

Retrieve a screenshot under Win32, if window handle is zero, capture the desktop.

By default, window decorations are not captured, if the decor parameter is set to true then window decorations are included.

screenshot id => window id
screenshot id => window id, display => display object

Retrieve a screenshot under X11, if id is zero, capture the root window. display object is a integer version of an X11 Display * , if this isn't supplied screenshot() will attempt connect to the the display specified by $ENV{DISPLAY}.

Note: taking a screenshot of a remote display is slow.


If no parameters are supplied:

  • if Win32 support is compiled, return screenshot(hwnd => 0).

  • if X11 support is compiled, return screenshot(id => 0).

  • otherwise, die.


Returns true if Win32 support is available.


Returns true if X11 support is available.

Imager::Screenshot::x11_open display name

Attempts to open a connection to either the display name in $ENV{DISPLAY} or the supplied display name. Returns a value suitable for the display parameter of screenshot, or undef.

Imager::Screenshot::x11_close display

Closes a display returned by Imager::Screenshot::x11_open().


Imager::Screenshot is licensed under the same terms as Perl itself.


Tony Cook <>