How to Annotate Images on Linux with Annotator

If you’ve ever tried to explain a Linux setting to a friend using only words, you already know the pain.
“Click the thing. No, the other thing. The other other thing.” This is why image annotation exists:
it turns “trust me” into “look right here,” with arrows, labels, blur boxes, and the occasional dramatic circle.

Annotator is a lightweight image markup app that helps you add callouts to screenshots (and regular images)
without launching a full-sized editor. It’s especially popular with people who write tutorials, file bug reports, teach,
or just want to point at something without typing a paragraph of directions.

What Annotator Is (and Why It’s Better Than “Just Draw an Arrow”)

Annotator is built for quick, clear communication. You load an image (from a file, clipboard, or a screenshot),
then layer on markup: text, shapes, arrows, counters, stickers, magnifiers, and blur. When you’re done, export to a format
that matches your goalPNG for crisp UI screenshots, JPEG for photos, PDF for shareable documents, or SVG when you want scalable output.

Highlights you’ll actually use

• Open images fast: file system, clipboard paste, drag-and-drop, and screenshot capture
• Clear callouts: arrows, boxes, circles, lines, and step counters (great for “Step 1, Step 2…” guides)
• Privacy tools: blur/obfuscate sensitive info (emails, IDs, addresses, serials)
• Zoom & magnifiers: make tiny UI details readable without enlarging the entire image
• Export options: common image formats plus PDF/SVG (and WebP on many builds)
• Undo/redo: because the first arrow is never the final arrow

Installing Annotator on Linux

You’ve got a few ways to install Annotator. The most universal route is Flatpak (works across many distros),
and it’s also the path that aligns with how Annotator is distributed for elementary OS.
If you prefer native packages, there are options for Ubuntu (PPA) and Arch (AUR), plus building from source.

Option 1 (Recommended): Install via Flatpak from elementary’s AppCenter repo

This is the “works on most distros” option. The basic idea:
install Flatpak → add the elementary AppCenter remote → install Annotator.

1. Install Flatpak (skip if you already have it).

   Examples:

2. Add the elementary AppCenter Flatpak remote

   Tip: --system installs for all users. If you prefer per-user installs, use --user.

3. Install Annotator

   Two common approaches (either is fine):

4. Launch Annotator

   You can launch from your app menu, or use:

Option 2: Ubuntu PPA (Ubuntu 20.04+)

If you prefer APT-managed installs on Ubuntu, a PPA is available. This can feel more “native” than Flatpak,
but it’s still a third-party repositoryso treat it like you would any external source: use it when you trust it,
and keep your system updated.

Option 3: Arch Linux (AUR)

On Arch-based distros, Annotator is commonly installed through the AUR. Use your preferred AUR helper:

Option 4: Build from source (for tinkerers)

If you want the full DIY route, building from source is possible (especially on Debian-based systems).
This is great for contributors or people who want to patch or test changes.

Expect a typical GTK/Vala toolchain setup (Meson, Vala compiler, GTK dev libraries, etc.), then run the project’s install script.
If that sentence made you smile, you’re the target audience.

Your First 3 Minutes in Annotator

1) Load an image (file, clipboard, or screenshot)

• From a file: open an image from your system (PNG/JPEG and other common formats work well).
• From clipboard: copy a screenshot, then paste into Annotator.
• Take a screenshot: if your build supports screenshot capture, grab full-screen/window/area, then annotate immediately.

2) Add markup layers that people can’t misinterpret

The best annotations are boring in the best way: consistent color, consistent thickness, and text that’s readable at a glance.
(If your text looks like it’s whispering, bump the font size.)

3) Export or copy/share

When you finish, export to a format that matches your destinationSlack, a ticketing system, a blog post, a PDF handout,
or an SVG that needs to scale cleanly.

Core Annotation Tools and When to Use Them

Text: the “explain it once” tool

Use text labels for names, settings, and short instructions. Keep labels short and action-oriented:
“Enable this,” “Set to 1080p,” “Click Save,” “Don’t touch this unless you enjoy trouble.”

Pro tip: Place text slightly away from the UI element and connect it with a line/arrow. That way your label doesn’t cover the button you’re trying to highlight.

Arrows, lines, boxes, circles: the classics that still win

Arrows are for direction (“this is the thing”). Boxes are for grouping (“these three settings live together”).
Circles are for emphasis (“this tiny icon matters”). Lines are for connecting (“this label refers to that switch”).

Keep a consistent style: one primary color for “do this,” another for “notice this,” and blur for “definitely don’t show this to the internet.”

Step counters: for tutorials that don’t cause migraines

If you’re writing instructions, counters are gold. A numbered dot or sequence marker makes your screenshot read like a map:
Step 1 is here, Step 2 is there, Step 3 is where you pretend you didn’t make a typo.

Magnifier tool: for tiny icons, tiny text, and tiny patience

When you need to show a small UI element without zooming the whole image, magnifiers help a lot.
Use them for toolbar icons, advanced settings toggles, or anything that looks like it was designed for ants with perfect eyesight.

Blur/obfuscate: the “save your future self” feature

Before you share a screenshot publicly, blur anything sensitive: email addresses, API keys, device IDs, account numbers,
unique URLs, faces, plates, or that one file name that reveals your entire personality.

If you’re posting to a bug tracker, you can still be helpful without oversharing. Blur first, regret never.

Stickers, icons, and saved shapes: when you want consistent visuals

Stickers/icons are great for visual shorthandthink warning symbols, arrows with personality, or UI-like glyphs.
If you make a lot of guides, saving custom shapes or reusing consistent elements helps your screenshots look like a set,
not a collection of unrelated chaos.

Three Practical Workflows (With Specific Examples)

Workflow 1: Create a “Click This” mini-guide for a teammate

1. Take a screenshot of the app or settings panel.
2. Paste into Annotator (clipboard) or open the file.
3. Add numbered counters in the order the user should click.
4. Add short text labels: “Open Settings,” “Select Network,” “Turn on VPN,” etc.
5. Export to PNG and drop it into chat/email.

Why it works: numbers remove ambiguity. Even if the UI changes slightly, readers still follow the sequence.

Workflow 2: File a bug report without leaking personal info

1. Capture the error message or glitch (screenshot).
2. Blur out usernames, hostnames, and any unique IDs.
3. Circle the exact UI element that triggers the problem.
4. Add a short label: “Clicking this crashes the app,” “Dropdown is blank,” “Text overlaps at 125% scaling.”
5. Export to PNG or PDF and attach it to the ticket.

This is the sweet spot: enough detail to reproduce, not enough detail to become a cautionary tale.

Workflow 3: Annotate a “before/after” photo (home, DIY, design)

1. Open your before photo and label what’s changing: “Replace faucet,” “Paint cabinets,” “Move shelving.”
2. Use boxes to group zones: “Lighting,” “Hardware,” “Backsplash.”
3. Add a magnifier for small finish details (tile pattern, screw placement, trim line).
4. Export as JPEG (photos) or PNG (if you have text-heavy callouts).

If you’re documenting progress, annotated photos become a project log you can actually understand months later.

Exporting: Pick the Right Format So Your Screenshot Doesn’t Betray You

PNG: best for UI screenshots

Use PNG when you want sharp text and crisp lines. It’s ideal for screenshots, diagrams, and anything where readability matters.

JPEG: best for photos (and smaller file sizes)

Use JPEG for photographs or image-heavy sharing where a little compression is acceptable.
If your annotation has lots of text, PNG may stay clearer.

PDF: best for “send it to someone who prints things”

PDF export is handy for sharing annotated visuals in a format that behaves consistently across systemsespecially for training handouts.

SVG: best when you need scalability (with a reality check)

SVG can be great for scalable output, but don’t assume every export round-trip will preserve editability the way layered design tools do.
A safe habit is to keep your original image and export versions as you go, rather than counting on reopening a “project file” later.

Speed and Polish Tips (So Your Markup Looks Intentional)

• Use a two-color rule: one color for “action,” one for “attention.” More colors = accidental circus.
• Standardize line thickness: thick enough to see, not thick enough to become modern art.
• Zoom in before placing small elements: your arrows will land where you meant, not where they felt like.
• Don’t cover UI labels: place text near the element, not on top of it.
• Blur first, then annotate: it’s easier to keep blur boxes aligned before the canvas gets crowded.
• Export a “final” copy: if you’re making a tutorial, do one last pass looking for cut-off text or overlapping callouts.

Troubleshooting Common Issues (Quick Fixes, Minimal Drama)

Annotator won’t launch (Flatpak)

• Try launching from terminal to see errors: flatpak run com.github.phase1geo.annotator
• Confirm the remote and install are correct: flatpak remotes and flatpak list
• If you just added remotes or portals, a restart/log-out can help (especially on Wayland-based desktops).

Screenshot capture behaves oddly on Wayland

Wayland is more secure by design, which often means screenshot tools rely on desktop portals.
If screenshot capture is flaky, make sure your portal services and the correct backend are installed for your desktop
(GNOME, KDE, etc.). Once portals are healthy, screenshot integrations are usually far more predictable.

“I can’t see my folders” or file access feels restricted

Flatpak apps use sandboxing. Normally, file pickers and permitted paths solve this cleanly.
If you need finer control, Flatpak permission managers (like Flatseal) can helpbut only grant what you actually need.
“Everything access forever” is how computers become urban legends.

Experiences in the Real World ( of “Here’s What You’ll Notice After You Use It for a While”)

People tend to discover Annotator in the same moment: the moment they realize they’ve typed “the button on the top right”
for the 400th time and nobody has ever clicked the correct button. The first experience is usually a small victory:
you paste a screenshot, draw one arrow, add one label, export, and suddenly your instructions land.
It feels unfair that one arrow can replace five messages, but that’s just the laws of communication doing their job.

The next “experience milestone” is learning restraint. Early on, it’s tempting to annotate everything:
circle every icon, label every panel, highlight every menu. But the most effective annotated images are selective.
You point to exactly what matters, and you leave the rest alone. In practice, that means you start using a consistent visual language:
a bright arrow means “click here,” a subtle box means “this section,” a blur rectangle means “private,” and a magnifier means
“this tiny thing is not optional.” Your screenshots start looking like they belong to the same tutorial series, even if you made them weeks apart.

Another common experience is realizing that privacy is not a “maybe later” stepit’s step zero.
The first time you almost post a screenshot with an email address, hostname, or unique URL, you become a blur enthusiast.
After that, blurring becomes automatic: capture → blur → annotate → export. It’s like washing your hands while cooking:
not glamorous, but you miss it immediately when you skip it.

If you annotate for teaching or support, you’ll also notice that numbered counters change everything.
A single screenshot with “1, 2, 3” markers can guide someone through a workflow faster than a paragraph of text,
especially if they’re stressed, new to the system, or switching between windows. The best part is that counters reduce back-and-forth:
people stop asking “Which menu?” because the menu is literally labeled “2.”

Long-term users also develop a habit of exporting versions. Not because they love clutter, but because iteration is real:
sometimes you’ll tweak a label, adjust an arrow, or realize the blur box missed a corner. Saving a clean “final” export
(and occasionally an earlier “draft” export) means you don’t have to recreate the whole composition from scratch.
It’s the annotation equivalent of saving your work before you do something experimental.

Finally, there’s a quiet joy in how Annotator fits into Linux life: it’s not trying to be a full design suite.
It’s the quick tool you reach for when you need clarity now. And once it becomes part of your routine, you’ll wonder how you ever
survived with nothing but text and hope.