Skip to main content
Version: 2.2 (dev)

Take screenshots

Use somewm-client for a direct capture, awful.screenshot for Lua integration, or grim with slurp for shell-based region selection.

Method 1: awful.screenshot (Interactive)​

Create the destination directory first:

mkdir -p ~/Pictures/screenshots

Add one binding to rc.lua:

local awful = require("awful")
local naughty = require("naughty")
awful.keyboard.append_global_keybindings({
awful.key({ modkey }, "Print", function()
local shot = awful.screenshot {
interactive = true,
directory = os.getenv("HOME") .. "/Pictures/screenshots/",
prefix = "shot",
}
shot:connect_signal("file::saved", function(_, path)
naughty.notification { title = "Screenshot saved", message = path }
end)
shot:refresh()
end, { description = "select screenshot region", group = "screenshot" }),
})

The file::saved signal reports that saving was attempted, but 2.1 does not check Cairo's write status before emitting it. Check the destination file if nothing appears.

Drag a rectangle to select the crop. Accepting the selection saves it. Escape cancels. Without directory, the default destination is $HOME.

The capture and selection use logical pixels at every output scale. See capture behaviour.

Delayed Capture​

To wait three seconds before selection:

local shot = awful.screenshot {
interactive = true,
auto_save_delay = 3,
}

For a noninteractive capture, call shot:save(path) rather than only refresh(). refresh() captures the image without saving it.

Method 2: somewm-client somewm-only​

Every command requires a destination path:

somewm-client screenshot save ~/Pictures/screenshot.png
somewm-client screenshot save ~/Pictures/transparent.png --transparent
somewm-client screenshot screen ~/Pictures/screen.png 1
somewm-client screenshot client ~/Pictures/window.png
somewm-client screenshot interactive ~/Pictures/region.png

interactive waits until you accept or cancel the selection. Cancellation returns an error status.

save captures the combined desktop. screen takes a screen index. client uses the focused window unless you append a client ID from client list.

Use absolute paths. Relative paths are resolved in the compositor's working directory. A shell expands unquoted ~, but an awful.spawn argument table does not:

awful.spawn({ "somewm-client", "screenshot", "save",
os.getenv("HOME") .. "/Pictures/screenshot.png" })

Method 3: grim + slurp​

Install grim, slurp and wl-clipboard from your distribution. Run these inside the Wayland session:

# Whole desktop
grim ~/Pictures/screenshot.png

# A selected region
grim -g "$(slurp)" ~/Pictures/region.png

# One output, using its connector name
grim -o DP-1 ~/Pictures/output.png

# Copy a capture to the clipboard
grim - | wl-copy

# Select a region and copy it
grim -g "$(slurp)" - | wl-copy

Use wlr-randr to find output names. grim -l sets PNG compression level, so it is not an output-listing command.

Keybinding Setup​

For a full capture, an argument table avoids shell quoting problems in paths:

awful.keyboard.append_global_keybindings({
awful.key({}, "Print", function()
local path = os.getenv("HOME") .. "/Pictures/"
.. os.date("screenshot_%Y%m%d_%H%M%S.png")
awful.spawn.easy_async({ "grim", path }, function(_, stderr, _, code)
naughty.notification {
title = code == 0 and "Screenshot saved" or "Screenshot failed",
message = code == 0 and path or stderr,
}
end)
end, { description = "capture desktop", group = "screenshot" }),
})

For a pipeline, use awful.spawn.with_shell, such as awful.spawn.with_shell('grim -g "$(slurp)" - | wl-copy'). A geometry crop captures what is visible in that rectangle, including overlapping windows. Use screenshot client when you want the client's own content.

Screenshot with Delay​

sleep 3 && grim ~/Pictures/screenshot.png

Annotating Screenshots​

With swappy installed:

grim -g "$(slurp)" - | swappy -f -

Troubleshooting​

  • Capture fails: check the command's error output, destination directory and WAYLAND_DISPLAY.
  • No output with the requested name: check the current connector names with wlr-randr.
  • Clipboard is empty: test printf 'test' | wl-copy, then wl-paste.
  • Wrong dimensions or missing areas: see Screenshots for the built-in capture's logical-coordinate and output-layout limits.

See Also​