Safe Eyes: a break reminder for Linux that respects your idle time

What the application does, and where it comes from

Safe Eyes protects your eyes from eye strain using what the repository description calls a simple and beautiful, yet extensible, break reminder.

The project is by Gobinath Loganathan and is licensed under GPL-3.0-or-later, with the `LICENSES/` directory and a `.reuse/` directory at the root indicating that the licensing is managed with the REUSE specification rather than a single file. The primary language in the metadata is Python, and the package version in the manifest is 3.5.1, matching the v3.5.1 release from 2026-09-05.

The distribution story is unusually wide, and it is the most useful thing in the README. The header carries badges for Debian unstable, the Arch User Repository, Flathub, PyPI and the Weblate translation status, and the README says the application is available from the official repositories of many popular distributions and that you can install on any Linux system with Python 3.

There is also a badge for the Awesome Humane Tech list, which places it among projects that reduce the harmful effects of technology on people, and that is a fair description of what a break reminder is.

The project is not archived, and the last push was on 2026-10-13, with releases v3.5.0 from 2026-04-23 and v3.4.1 from 2026-04-19. The manifest classifies it as Development Status 5, Production/Stable, with the environment as X11 Applications, GTK, and the intended audience as end users and desktop.

The command line, which is more capable than the window

The application exposes a full command line, and it is worth reading because most of the useful actions are available without touching the interface.

  -a, --about                show the about dialog
  -s, --settings             show the settings dialog
  -t, --take-break           take a break now
  -b, --short-break          take a short break now
  -l, --long-break           take a long break now
  -d, --disable              disable the currently running Safe Eyes instance
  -e, --enable               enable the currently running Safe Eyes instance
  -q, --quit                 quit the running Safe Eyes instance and exit
  --status                   print the status of running Safe Eyes instance and exit
  --debug                    start Safe Eyes in debug mode

The distinction between `take-break` and `short-break` and `long-break` is the interesting part. You can pull a break forward on demand, and you can choose which kind of break you want, which suggests that breaks are not all the same length and that the user is trusted to know whether they need twenty seconds or five minutes.

The instance management flags, `--disable`, `--enable`, `--quit` and `--status`, all act on the currently running instance rather than starting a new one. That is a deliberate design: the application is a single background daemon with a window that appears over it, and a user who wants to turn it off for a presentation does not want to hunt for a menu, and a script that wants to know whether it is running can ask.

`--status` printing the status and exiting, and `--debug` starting in debug mode, are the two flags a bug reporter needs.

Installing it, and the dependency list for a source build

The README covers the distributions individually, and the commands are short.

For Ubuntu, Linux Mint and other Ubuntu derivatives, there is an official PPA hosting the latest version for Ubuntu 22.04 and above:

sudo add-apt-repository ppa:safeeyes-team/safeeyes
sudo apt update
sudo apt install safeeyes

For Arch it is `yay -S safeeyes`, for Gentoo `sudo emerge -av x11-misc/safeeyes`, for Debian `sudo apt-get install safeeyes`, for openSUSE Tumbleweed `sudo zypper refresh` followed by `sudo zypper install safeeyes`, and for Alpine `sudo apk add safeeyes`.

Fedora is the one distribution with an extra note, because it installs with pip:

pip3 install --user safeeyes

and it needs two extras depending on the display server. For smart pause in Wayland you install the `python3-pywayland` package, and for the smart pause plugin in X11 you may need the latest xprintidle.

The source dependencies are listed explicitly, which is helpful:

- `gir1.2-notify-0.7`
- `gir1.2-gtk-4.0`
- `ffmpeg` or `pipewire` (any of them works)
- `python3` (>= 3.11.0)
- `python3-gi`
- `python3-babel`
- `python3-croniter`
- `python3-packaging`
- `python3-xlib` (required on x11)
- **Optional**: Either `python3-pywayland` (provides smartpause in Wayland) or `xprintidle` (provides smartpause in x11).

So the app is GTK4 with desktop notifications, needs ffmpeg or pipewire for something in the break window, and needs one of two idle-detection mechanisms depending on your display server.

The Flatpak warning, and what the README says to do instead

The Flatpak section is the part of the README worth reading before you install anything.

The install is one command, `flatpak install flathub io.github.slgobinath.SafeEyes`, and the Flatpak version comes with its dependencies and features automatic updates.

But it opens with a warning: many plugins and features do not work well in the flatpak, and the project recommends that you use one of the native packages listed above. Flatpak-only bugs should be reported to the Flathub repository rather than to the main repository.

That is an unusual and useful thing for a project to say about its own most convenient install route. A Flatpak breaks sandboxing in ways that are easy to predict here. The plugins and the smart pause feature both need to talk to the session and the display server, and the smart pause needs to read the idle time of the X server or the Wayland compositor, which a sandbox is not going to let it do without permissions. A break reminder that cannot tell when you are actually away from the keyboard is a break reminder that interrupts you while you are reading.

So the guidance is: use the Flatpak if you want the easy install and do not need the plugins, and use a native package if you do.

There is a third option for systems whose repositories lack matching dependencies, such as CentOS, which the README handles with a virtual environment: install the CentOS 7 build dependencies, create a venv in your home folder, activate it, and install safeeyes with pip. The Python packaging in `pyproject.toml` supports this, with the console script declared as `safeeyes = safeeyes.__main__:main`.

Running from source, and the icon problem on Wayland

Running from source takes three commands:

git clone https://github.com/slgobinath/safeeyes.git
cd SafeEyes
python3 -m safeeyes

And then there is the caveat, which is more interesting than the commands. Safe Eyes installers install the required icons to `/usr/share/icons/hicolor`, and when you run Safe Eyes from source without that, some icons may not appear.

The reason, in the README's own explanation, is that on Wayland this may still not be enough to get the window icons working properly, because Wayland requires the `.desktop` file to match the running application, which is hard to do when running from source. If at all possible, prefer using an installed package.

That is a Wayland-specific constraint rather than a packaging bug. On X11, an application can set its window icon directly and it will be displayed. On Wayland the client is not allowed to draw its own icon, so the icon comes from the desktop entry matching the running application, which means a source checkout has to have its desktop file installed and correct.

There is a similar note for ChromeOS, where the Linux container is actually Debian. You enable the container and install with apt, and while no tray icon is available, the application still runs in the background and shows breaks as usual, and you can still change the settings from the application menu or by running `safeeyes -s`.

The Python packaging, and the localisation build

The `pyproject.toml` describes a small, well-organised package.

The runtime dependencies are four: PyGObject, which is the GObject introspection binding the GTK application is built on, babel for the internationalisation, packaging for version comparison, and python-xlib, the X11 client library used for the idle detection. There are two optional dependency groups. `healthstats` pulls in croniter, and `wayland` pulls in pywayland, which is the Wayland counterpart of the X11 idle support.

The development dependencies are grouped by purpose, and the grouping is a good sign. The lint group pins ruff at 0.11.2, the scripts group pins polib at 1.2.0, the types group has mypy at 1.15.0 with PyGObject-stubs and type stubs for croniter and python-xlib, and the tests group has pytest at 9.0.3 and time-machine at 2.16.0. The last one is the interesting choice, because time-machine lets a test control the clock, and for a break reminder the clock is not a detail, it is the subject of the application.

The `setup.py` shows a custom build step. There is a `BuildCommand` subclass with an extra sub-command, `BuildMoSubCommand`, which compiles the `.po` translation files into `.mo` binaries using `msgfmt` and creates the parent directories as needed. That is a build hook rather than a packaging trick, and it is why the repository has `update-po.sh`, `update-version.sh` and `validate_po.py` at the root.

The translations themselves are managed on Weblate, with a status badge in the README header, and the application is available in a range of languages as a result.

Where Safe Eyes is the wrong choice

The first wrong case is a distribution with no native package and a Flatpak that breaks what you need. The README's own recommendation is to use a native package, and if your distribution has none, the virtual environment route is the fallback, which means managing the dependencies yourself.

The second is a user who needs the smart pause feature on a display server where it is not supported. The README is explicit that the idle detection comes from `python3-pywayland` on Wayland or `xprintidle` on X11, and neither is present by default on every system. Without one of them, the application cannot tell an idle screen from a focused one, and you get breaks while you are reading.

The third is a macOS or Windows user. The manifest classifies the environment as X11 Applications, GTK, and the operating system as POSIX Linux, and the whole packaging table is Linux distributions. There is nothing for other platforms here.

The fourth is a team that wants a workplace policy tool. This is a personal wellbeing application that reminds one person to take a break, with a GUI and a tray icon, and it has no reporting, no enforcement and no central configuration. If the goal is to make sure people take breaks, this is the wrong kind of software.

The fifth is anyone who finds a break reminder annoying. That is a matter of configuration, and the settings dialog exists, but it is worth saying plainly that the value of this application is entirely in the reminder being tolerable, and a user who has already failed to stop using a desktop reminder will not be persuaded by a nicer one.

Editorial conclusion

Safe Eyes suits a Linux user who sits at a screen all day and wants a break prompt that follows the 20-20-20 habit without being a nagging window, and who is on a distribution with a native package. It does not suit a user on a distribution without a native package, because the README warns that many plugins and features do not work well in the Flatpak and recommends a native package instead. Before installing it, check whether the distribution has a native package, and if you use it, note that the smart pause feature needs `python3-pywayland` on Wayland or `xprintidle` on X11, and that running from source leaves the window icons broken because Wayland requires the desktop file to match the running application.

Frequently asked questions

Official sources

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