Hop on Linux

Note

Hop for Linux is new in 0.1.5. Hop Island and Hop Clipper both run on Linux. Like Hop on Windows it's in early development: if something doesn't work on your desktop, please open an issue and say which distro and desktop you use.

Linux Hop is one app for every desktop. Each time it starts, it checks whether you're on X11 or Wayland and which desktop you use. If your system later moves from X11 to Wayland (Ubuntu, Fedora and Xubuntu all are), Hop keeps working.

So the only choice you make is the package type, and that depends on your distro.

Which one am I on?

Open a terminal (on Xubuntu: Ctrl+Alt+T) and run these two commands.

1. Your distro: which package

grep -E '^(NAME|ID|ID_LIKE)=' /etc/os-release

Look at ID and ID_LIKE:

For example, Xubuntu prints:

NAME="Ubuntu"
ID=ubuntu
ID_LIKE=debian

That's a .deb.

2. Your desktop: how F8 works there

echo "$XDG_SESSION_TYPE $XDG_CURRENT_DESKTOP"

If the first word is empty, ask your system directly:

loginctl show-session "$XDG_SESSION_ID" -p Type -p Desktop

Install the .deb

Download the package from the GitHub release and install it with apt, which also installs everything Hop needs:

cd ~/Downloads
curl -LO https://github.com/preinfection/hop/releases/download/v0.1.5/hop_0.1.5_all.deb
sudo apt install ./hop_0.1.5_all.deb

Keep the ./: it tells apt to install the file you downloaded rather than look for a package called hop online.

Then start Hop Island and Hop Clipper from your app menu, or in a terminal:

hop-island &
hop-clipper &

Both start by themselves when you log in from now on.

Install the .rpm

On Fedora:

cd ~/Downloads
curl -LO https://github.com/preinfection/hop/releases/download/v0.1.5/hop-0.1.5-1.noarch.rpm
sudo dnf install ./hop-0.1.5-1.noarch.rpm

Then start them the same way: hop-island & and hop-clipper &, or from the app menu.

Note

Fedora's own FFmpeg can't encode H.264, which clips use. If Hop Clipper can't save, add RPM Fusion and its full FFmpeg:

sudo dnf install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf swap ffmpeg-free ffmpeg --allowerasing

Run the AppImage

An AppImage is one file you run. Download it, make it runnable, and start it:

mkdir -p ~/Applications && cd ~/Applications
curl -LO https://github.com/preinfection/hop/releases/download/v0.1.5/Hop-0.1.5-x86_64.AppImage
chmod +x Hop-0.1.5-x86_64.AppImage
./Hop-0.1.5-x86_64.AppImage

It starts Hop Island and Hop Clipper together, and the first start adds Hop to your app menu and to start on login.

Hop's AppImage uses your system's Python, GTK and WebKit (they are too big to pack inside). If something is missing, it tells you the one command to install it. On Arch:

sudo pacman -S --needed python-gobject webkit2gtk-4.1 tk python-pillow python-numpy python-psutil python-cffi ffmpeg playerctl xorg-xprop xorg-xdpyinfo

Tip

If it says dlopen(): error loading libfuse.so.2, your system is missing FUSE 2, which AppImages use:

sudo apt install libfuse2t64     # Ubuntu 24.04 and newer
sudo pacman -S fuse2             # Arch

Check your download

Each release lists the SHA-256 checksum of every file (SHA256SUMS-0.1.5.txt). Compare it with what your copy prints:

sha256sum hop_0.1.5_all.deb

Use the name of the file you downloaded. If the two match, your file is exactly the one published on GitHub.

Wayland: the F8 key and what Clipper records

Hop's windows run through XWayland, which every Wayland desktop includes, so the island sits on top of everything on GNOME, KDE, Hyprland and Sway with nothing extra to install.

Wayland doesn't let apps listen for keys in other windows, so F8 is a shortcut of your desktop's that runs hop-clipper --save:

• GNOME: added by Hop on first start. Change the key in Settings → Keyboard → Custom Shortcuts.
• KDE: System Settings → Shortcuts → Add New → Command or Script, command hop-clipper --save, key F8.
• Hyprland: add bind = , F8, exec, hop-clipper --save to ~/.config/hypr/hyprland.conf.
• Sway: add bindsym F8 exec hop-clipper --save to ~/.config/sway/config.

With the AppImage, the command is ~/Applications/Hop-0.1.5-x86_64.AppImage --clipper --save.

Important

On Wayland, Hop Clipper records the windows that run through XWayland. That covers most games (Steam and Proton, Wine, Roblox through Sober…), but apps drawn natively for Wayland (some browsers, the GNOME apps) come out black in clips. On X11 desktops like Xubuntu, everything is recorded.

Run it from GitHub

You can run Hop straight from its source code instead of a package. This is for people who want to change Hop or try the newest code.

1. Install what Hop needs

Ubuntu, Xubuntu, Mint, Debian:

sudo apt update
sudo apt install git python3 python3-venv python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-webkit2-4.1 \
  python3-tk python3-pil python3-pil.imagetk python3-numpy python3-psutil python3-cffi ffmpeg playerctl x11-utils

Fedora:

sudo dnf install git python3 python3-gobject gtk3 webkit2gtk4.1 python3-tkinter python3-pillow python3-pillow-tk \
  python3-numpy python3-psutil python3-cffi ffmpeg-free playerctl xprop xdpyinfo

Arch, Manjaro:

sudo pacman -S --needed git python python-gobject gtk3 webkit2gtk-4.1 tk python-pillow python-numpy python-psutil \
  python-cffi ffmpeg playerctl xorg-xprop xorg-xdpyinfo

2. Get the code

git clone https://github.com/preinfection/hop.git ~/hop
cd ~/hop

3. Set up Python

A virtual environment keeps Hop's three Python packages apart from your system's. --system-site-packages lets it use the GTK and WebKit you installed in step 1:

python3 -m venv --system-site-packages .venv
source .venv/bin/activate
pip install -r requirements-linux.txt

4. Start Hop

python island/host.py &
python clipper/clipper.py &

The & keeps your terminal free. To stop them: python island/host.py --quit and python clipper/clipper.py --quit.

5. Start on login (optional)

Packages set this up for you. From source, turn on Start at login in Hop Island's settings, or add the entries yourself:

mkdir -p ~/.config/autostart
printf '[Desktop Entry]\nType=Application\nName=Hop Island\nExec=%s/.venv/bin/python %s/island/host.py\n' ~/hop ~/hop > ~/.config/autostart/hop-island.desktop
printf '[Desktop Entry]\nType=Application\nName=Hop Clipper\nExec=%s/.venv/bin/python %s/clipper/clipper.py\n' ~/hop ~/hop > ~/.config/autostart/hop-clipper.desktop

Updating from GitHub

cd ~/hop
git pull
source .venv/bin/activate
pip install -r requirements-linux.txt

Then start both apps again (a new copy replaces the running one).

Making the packages yourself

The same script that makes the release's packages works on any Ubuntu or Debian (WSL too). It needs fpm (sudo gem install fpm), rpm and appimagetool:

bash installer/linux/build.sh

The .deb, .rpm and AppImage land in build/linux/, with their checksums.

Get updates with APT or DNF

Add Hop's repository once, and new versions arrive with your normal system updates.

Ubuntu, Xubuntu, Mint, Debian

curl -fsSL https://gethop.lol/apt/hop.gpg | sudo tee /usr/share/keyrings/hop.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/hop.gpg] https://gethop.lol/apt stable main" | sudo tee /etc/apt/sources.list.d/hop.list
sudo apt update && sudo apt install hop

Fedora

sudo curl -fsSLo /etc/yum.repos.d/hop.repo https://gethop.lol/rpm/hop.repo
sudo dnf install hop

Both repositories are signed with Hop's key 89A1 86DA 9E05 D9CA 6011 4A1C EF48 75B7 0F1A 7463. Your package manager checks that signature on every update.

Updating a package

With the repository above, sudo apt upgrade or sudo dnf upgrade picks up new versions. Otherwise, install the newer package the same way you installed the first one. apt and dnf replace the old version and keep your settings. For the AppImage, download the new file and delete the old one.

Uninstalling

sudo apt remove hop          # .deb
sudo dnf remove hop          # .rpm
rm ~/Applications/Hop-*.AppImage ~/.local/share/applications/hop.desktop ~/.config/autostart/hop.desktop   # AppImage

Your settings stay behind in case you come back. To remove them too:

rm -rf ~/.config/LyricsIslandLite ~/.config/Hop ~/.local/share/"Hop Island" ~/.local/share/clipper

Clips are in ~/Videos/Hop Clips. Delete that folder yourself if you don't want them.

Troubleshooting

The island has a black box around it

See-through windows need your desktop's compositor. On Xubuntu, open Settings → Window Manager Tweaks → Compositor and turn on Enable display compositing, or run:

xfconf-query -c xfwm4 -p /general/use_compositing -s true

F8 does nothing

• On X11, another app may already use F8. Close it, or save from the island's record button.
• On Wayland, check the shortcut from the Wayland section.
• Check that Hop Clipper runs: hop-clipper --save in a terminal says nothing when it does.

Music doesn't show up

Hop reads music through MPRIS, which Spotify, Firefox, Chrome, Brave, VLC and most players support. To see what your system reports:

playerctl -l
playerctl metadata

If playerctl doesn't list your player, Hop can't see it either. In browsers, check that "hardware media key handling" isn't turned off.

Clips have no sound

Hop Clipper records what your speakers play through PulseAudio or PipeWire. Check that one runs:

pactl info | grep 'Server Name'