Annotate Screenshots with Flameshot

Flameshot is one of the few screenshot tools that combines fast capture, a full annotation toolkit, and optional cloud upload in a single lightweight application. It works on X11 out of the box and has made steady progress on Wayland — usable today with a few caveats. This guide walks through installation, setting a global keyboard shortcut, annotating captures, and uploading results.

Install Flameshot

Debian / Ubuntu

sudo apt update && sudo apt install flameshot

Fedora

sudo dnf install flameshot

RHEL 9 / Rocky Linux 9

Enable EPEL first, then install:

sudo dnf install epel-release
sudo dnf install flameshot

Arch Linux

sudo pacman -S flameshot

Verify the installed version — you want at least 12.x for Wayland improvements:

flameshot --version

Set a Global Keyboard Shortcut

Most desktop environments do not wire up Flameshot automatically. Set Print Screen (or any key you prefer) to launch it.

GNOME (Settings → Keyboard → Custom Shortcuts)

1. Open Settings → Keyboard → View and Customize Shortcuts → Custom Shortcuts.
2. Click +, name it "Flameshot", set command to flameshot gui.
3. Assign Print Screen as the shortcut.

KDE Plasma (System Settings → Shortcuts)

1. Go to System Settings → Shortcuts → Custom Shortcuts.
2. Create a new Global Shortcut → Command/URL entry.
3. Command: flameshot gui, trigger: Print.

XFCE / Other WMs

Use your DE's keyboard settings or a tool like xbindkeys. For XFCE, go to Settings → Keyboard → Application Shortcuts and add flameshot gui bound to Print.

systemd autostart (optional, for system tray)

Running Flameshot in the tray gives faster startup and lets you access its history. Create an autostart entry:

mkdir -p ~/.config/autostart
cp /usr/share/applications/org.flameshot.Flameshot.desktop ~/.config/autostart/

Or enable the included systemd user service if your distro ships it:

systemctl --user enable --now flameshot

Capture and Annotate

Press your shortcut (or run flameshot gui from a terminal). The screen dims and a crosshair appears. Click and drag to select the region you want to capture.

The annotation toolbar appears at the edge of your selection. Key tools:

• Pencil / Marker — freehand drawing.
• Rectangle / Circle — outline or filled shapes to highlight areas.
• Arrow — point at specific elements.
• Text — add labels; click the tool, then click where you want text.
• Pixelate / Blur — hide sensitive data before sharing.
• Color picker & thickness slider — bottom-left of the toolbar.
• Undo — Ctrl+Z works at any point.

When you are satisfied, click the floppy-disk (Save) icon to write a PNG to disk, or the clipboard icon to copy directly. The default save path is ~/Pictures; change it under Flameshot → Configuration → General → Save Path.

Upload to Imgur

Flameshot has built-in Imgur upload. After annotating, click the cloud-upload icon in the toolbar. A browser window opens to confirm the upload; the direct link is copied to your clipboard automatically.

You can also upload from the command line without the GUI:

flameshot gui --upload

If you do not want a browser confirmation dialog every time, configure it:

flameshot config --tray false   # example: disable tray icon instead
flameshot config --help         # list all CLI config flags

Upload to a Self-Hosted Server

Flameshot does not have native support for arbitrary upload targets (ShareX-style), but you can pipe output to a script using the --raw-image flag:

flameshot gui --raw-image | curl -s -F "file=@-" https://your.server/upload.php

A popular self-hosted pairing is Zipline or XBackBone. The pattern is the same: capture raw PNG from Flameshot's stdout, POST it with curl, and parse the JSON response for the URL. Wrap this in a shell script and bind the script to your shortcut instead of flameshot gui directly.

Example wrapper script at ~/.local/bin/flameshot-upload.sh:

#!/usr/bin/env bash
URL=$(flameshot gui --raw-image | \
  curl -s -F "file=@-;filename=shot.png" \
       -H "Authorization: Bearer YOUR_TOKEN" \
       https://your.server/api/upload | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")
echo "$URL" | xclip -selection clipboard
notify-send "Screenshot uploaded" "$URL"

chmod +x ~/.local/bin/flameshot-upload.sh

Wayland Support

Flameshot's Wayland story improved significantly in version 12. The current status:

• GNOME on Wayland: Works via the XDG Desktop Portal screenshot interface. The annotation GUI launches normally. Keyboard shortcuts set through GNOME Settings work. One limitation: Flameshot cannot capture a region of a specific window without a brief full-screen grab first.
• KDE Plasma on Wayland: Functional as of Plasma 5.27 / Flameshot 12. Region selection and annotation work. The system tray icon behaves correctly.
• Sway / wlroots compositors: Requires xdg-desktop-portal-wlr installed and running. Set the environment variable before launching:

export XDG_CURRENT_DESKTOP=sway
flameshot gui

• Fallback — XWayland: If you hit rendering issues, forcing Flameshot onto XWayland is a reliable workaround while native support matures:

DISPLAY=:0 flameshot gui

Check whether your session is X11 or Wayland before debugging:

echo $XDG_SESSION_TYPE

Output will be x11 or wayland.

Verify Everything Works

1. Press your keyboard shortcut — the screen should dim and show the crosshair cursor.
2. Draw a selection, add a text annotation, and save to ~/Pictures.
3. Check the file exists: ls -lt ~/Pictures | head -3
4. Test clipboard copy by pasting into an image editor or browser address bar (Ctrl+V in most apps that accept images).
5. If using Imgur upload, verify the returned URL opens the annotated image in a browser.

Troubleshooting

Shortcut does nothing on Wayland / GNOME

GNOME may intercept Print Screen for its own screenshot tool. Go to Settings → Keyboard → System → Screenshots and disable or reassign the conflicting built-in shortcut, then re-set your Flameshot binding.

Blank / black capture on Wayland

Install or restart the XDG portal: systemctl --user restart xdg-desktop-portal. On GNOME also ensure xdg-desktop-portal-gnome is installed. If it persists, use the XWayland fallback above.

Annotation toolbar not visible

With multi-monitor setups, the toolbar sometimes spawns off-screen. Try selecting a region closer to the center of your primary display, or run flameshot config and check the Show Toolbar checkbox.

Imgur upload fails with network error

Imgur's anonymous upload API occasionally rate-limits requests. Try again after a minute, or switch to a self-hosted solution as described above.