Gradia, a GNOME screenshot editor that fixes the framing before you post

The problem is presentation, not capture

Gradia addresses a narrow but real annoyance. Screenshots of application windows are often transparent, or oddly proportioned, and they look wrong the moment they land in a social media feed. The fix is usually straightforward, but the work of cropping, padding, adding a colored background and rounding the corners is tedious enough that most people simply post the raw capture instead.

The project describes the goal as making screenshots ready for the world, and the rest of the README stays close to that: quickly modify screenshots of application windows to put them better in context. So this is not a general purpose image editor with a screenshot feature attached. It is a screenshot post processor with an opinion about how the result should look, which is why the whole application can be small enough to feel like a utility rather than a suite.

The design language follows the platform it targets. The repository carries a GNOME Circle badge, the topics list GTK4 and libadwaita, the data directory holds a scaled application icon under the be.alexandervanhee.gradia identifier, and the GNOME Code of Conduct is declared as applying to the project. The application is a Python program built on GTK4, packaged with Meson and Flatpak, with translations kept in a po/ directory.

Launching straight from the screenshot shortcut with a flag

The most interesting feature is the least obvious one, and it is documented as an optional extra rather than a headline. Gradia can be wired into the desktop screenshot flow so that taking a screenshot opens the editor immediately with the new image already loaded. The README walks through it as a GNOME keyboard shortcut setup, and the actual mechanism is a command line flag on the Flatpak application id.

flatpak run be.alexandervanhee.gradia --screenshot=INTERACTIVE

The path to set it up is Settings, then Keyboard, then View and Customize Shortcuts, then Custom Shortcuts, where you add a new entry, name it something like Open Gradia with Screenshot, and paste the command above. The README suggests Ctrl plus Print as a shortcut, noting that it should be free by default. A second mode takes the picture of all existing screens right away:

flatpak run be.alexandervanhee.gradia --screenshot=FULL

The difference between the two modes is what happens next. The interactive variant lets you select a region, which is the familiar screenshot interaction, while the full variant captures everything that is on the desktop instantly and hands that to the editor. Either way the point is the same: the editor is not a separate trip to a file manager after the capture, it is the next screen in the sequence.

A Flatpak app with a different OCR build

The build system has an unusual detail that only shows up when you look at the flatpak manifest. There are two configurations, the regular one and a Devel one, and the README states plainly that the Devel configuration includes everything required for OCR. That sentence carries a lot of weight in practice. The stable build you install from Flathub or the Snap Store does not carry the OCR dependencies, and text recognition inside the editor is therefore tied to the development build rather than to the packaged one.

The Python side is small and mostly one library. pyproject.toml names the project Gradia, requires Python 3.9 or newer, and configures Pyright against a local venv directory. requirements.txt contains a single runtime dependency, Pillow, with a comment that warns you to use a Pillow build that includes webp and avif support. That comment matters for a screenshot tool, since the formats people actually share tend to be the modern ones.

The packaging pipeline around that is documented in the same file, with a sequence of shell steps for regenerating the flatpak pip dependencies. The instructions point at the flatpak-pip-generator script, install the requirements-parser package, run the generator against requirements.txt and move the resulting file into the build-aux directory:

./flatpak-pip-generator --requirements-file=requirements.txt --output pypi-dependencies

So the dependency graph of the application is one imaging library, and the complexity lives in how that library is vendored into a sandbox.

Building from source with GNOME Builder

The documented development path runs through GNOME Builder, which is the consistent choice for a project that ships a Flatpak and follows GNOME conventions. The steps are deliberately short: install Builder from Flathub, use the Clone Repository button in the bottom right and enter the repository URL, then find the dropdown next to the be.alexandervanhee.gradia.json text at the top of the window. That dropdown selects the active configuration, either the Devel flatpak build file or the regular one, and the Run button builds and launches it.

The choice of configuration in that dropdown is the same choice discussed above, so the Devel option is where you go when you need OCR, and the regular one is the closer match to what users get from the stores.

The repository layout supports that workflow. A meson.build and meson.options sit at the root alongside pyproject.toml, requirements.txt and requirements-dev.txt, the application code lives in a gradia/ directory, static resources in assets/ and data/, translations in po/, and a web/ directory holds the project site, with scripts/ and build-aux/ for tooling. There is also a Gradia.doap file, the standard GNOME metadata document for listing the application in software directories, and a TRANSLATING.md file for translators. GNOME Builder is not the only way to run the code, but it is the way the project documents.

Distribution channels, and the ones nobody supports

Gradia is available through two official channels. The README carries a Flathub badge for be.alexandervanhee.gradia and a Snap Store badge for gradia, and the application is also listed on apps.gnome.org. The Flathub channel is the one the project builds for, given the GNOME Builder instructions and the flatpak manifest, and the Snap package exists alongside it.

Under a separate heading the README collects unofficial packages, marked with a warning that these methods are not officially supported and that issues related to packaging in this way should be reported outside the project bug tracker. A Repology badge tracks the version available across the various Linux distribution repositories. The distinction matters if you hit a bug: whether your Gradia came from Flathub, the Snap Store or a distribution package decides where the report belongs, and a distribution package that lags behind Flathub is the most likely source of version differences.

The project is licensed under GPL-3.0, with the COPYING file at the repository root carrying the terms. That licence obligation is the usual one for this class of software, and it is the reason the source is published in the first place, but it also means a modified build you distribute has to stay under the same terms. The application is also supported by individual sponsorship through a funding link in the header.

What Gradia is not, and the alternative worth naming

The limits of the tool follow from its scope. It is a desktop application, so there is no batch mode and no command line pipeline for processing a folder of captures; the only command line surface documented is the screenshot flag that the shortcut uses. It is also not a photo editor. The README frames the feature set as editing images to fix display problems and enhance their appearance, and it does not document layers, curves, colour grading, selection tools beyond the capture, or the export formats it produces.

The alternative to name here is the built-in desktop capture itself, which is what the shortcut flow replaces. A stock GNOME screenshot, whether taken with the keyboard shortcut or through a screenshot application, produces a flat file with no framing, and the work of making it presentable is left to you and to a general image editor. Gradia takes the opposite approach: it keeps the capture in a dedicated application that is built around the single job of presentation, and it exposes that application to the desktop through a command so the two steps become one. The difference in approach is not that Gradia captures better, it is that Gradia removes the gap between capturing and formatting, at the cost of being unable to do anything else with the image.

For a user who needs both, the usual combination is Gradia for the framing and a general editor afterwards, and the screenshot is a file you can open anywhere. For a user who only needs the framing, Gradia alone is enough, and the official distribution channels make that path cheap to try.

Editorial conclusion

Gradia suits Linux users who publish window screenshots and want a framed, consistent result without opening a general image editor, and it fits anyone already on Flathub or Snap. It is the wrong tool for batch processing, for a design workflow that needs per-pixel work, or for a machine where the Flathub build is enough but text extraction is expected, since the OCR dependencies are only in the Devel configuration. Before committing, check the version your distribution ships, because pyproject.toml reads 1.14.0 while the newest tagged release is v1.13.0 from 2026-04-24, and the last push was on 2026-09-30.

Frequently asked questions

Official sources

1. AlexanderVanhee/Gradia on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases