GPaste

GPaste

GPaste is a clipboard management system for GNOME: a daemon that remembers what you copy, plus a GTK 4 interface, a GNOME Shell extension and a CLI to get it back.

New to the idea? This post explains what clipboard managers are for.

Features

• Persistent history across sessions, with several named histories you can switch between, back up and delete independently.
• Everything you copy: plain text, rich text and HTML, images (de-duplicated by checksum, kept as files or as database blobs depending on the storage backend), URIs and colours.
• Encryption at rest — an optional libsodium-backed history, with the passphrase optionally kept in the keyring.
• Pluggable storage: an XML file, a per-history SQLite database that persists incrementally, or nothing at all. Switch at any time from the preferences or with gpaste-client migrate.
• Passwords: mark an item as a password to have it shown as a name instead of its contents, and excluded from the plain-text history. Give it a timeout and the clipboard stops handing it out once that runs out. A text a password manager marks as a secret (KDE's x-kde-passwordManagerHint) is taken in as a password on its own, and GPaste marks the passwords it puts on the clipboard the same way, so other clipboard managers can recognise them. Current GTK advertises the marker on X11 but cannot serve its value, so other managers may not recognise GPaste passwords there. Deleting a password entry clears its selection, including after a rename; a separate named entry with the same value is kept distinct.
• Favourites: pin an item and the history never drops it on its own — the size and memory limits give way instead. Filter the list down to the pinned items from the UI, the extension or gpaste-client --favourites.
• Search, merge and edit items from the UI, the extension or the CLI.
• GNOME Shell integration through a native extension, whose menu names the history in use and switches to, creates, empties, backs up or deletes one, with an optional experimental mode that runs the daemon inside the Shell itself.
• Global shortcuts through the XDG portal, so they work the same on Wayland and X11, and one switch in the preferences turns every one of them off.

Installation

Fedora

sudo dnf install gpaste gpaste-ui gnome-shell-extension-gpaste

Arch Linux

sudo pacman -S gpaste

One package: it ships the daemon, the graphical tool and the extension together.

Debian and Ubuntu

sudo apt install gpaste-2 gnome-shell-extension-gpaste

The digit tracks the library API version, so it becomes gpaste-3 once this release lands. Ubuntu's copy lives in universe and lags a long way behind — several major versions, even on the current LTS — while Debian unstable keeps up.

openSUSE

sudo zypper install gpaste

Elsewhere

GPaste is packaged in plenty of other distributions — Alpine, nixpkgs, Void and Gentoo among them. Repology tracks which version each one ships.

Wherever it came from, enable the extension in the Extensions app once it is installed.

From source

On Fedora and other rpm-based distributions:

# Build dependencies
sudo dnf install meson ninja-build gcc gettext-devel \
                 glib2-devel gtk4-devel libadwaita-devel gcr-devel \
                 libXfixes-devel dbus-devel gnome-control-center \
                 gobject-introspection-devel vala mutter-devel

# Optional, but on by default when found
sudo dnf install libsodium-devel sqlite-devel libsecret-devel \
                 libpwquality-devel

On Debian, Ubuntu and other deb-based distributions:

# Build dependencies
sudo apt install meson ninja-build build-essential pkg-config gettext \
                 libglib2.0-dev libgtk-4-dev libadwaita-1-dev libgcr-4-dev \
                 libxfixes-dev libdbus-1-dev systemd-dev gnome-control-center-dev \
                 gobject-introspection libgirepository1.0-dev valac
# and the libmutter-N-dev of the mutter GNOME Shell runs on

# Optional, but on by default when found
sudo apt install libsodium-dev libsqlite3-dev libsecret-1-dev libpwquality-dev

mutter is wanted for the GNOME Shell extension and the clipboard backend it hosts, gobject-introspection for the typelibs the extension loads and for the bindings, and vala for the Vala ones: -Dgnome-shell=false -Dintrospection=false -Dvapi=false builds without all three, and without the extension and the bindings. dbus, systemd and gnome-control-center are wanted for their pkg-config files alone, which say where the D-Bus service and interface files, the systemd user unit and the control-center keybinding files go. Fedora ships systemd's in the base package, which is why only the apt line names it, and Debian ships gnome-control-center's in its -dev package. A packager who would rather not pull any of them in can name the four directories outright — -Ddbus-services-dir, -Ddbus-interfaces-dir, -Dsystemd-user-unit-dir and -Dcontrol-center-keybindings-dir — and dbus and gnome-control-center are still needed at runtime either way.

Then, wherever you are:

git clone https://github.com/Keruspe/GPaste.git
cd GPaste
meson setup build --prefix=/usr
ninja -C build
sudo ninja -C build install
sudo glib-compile-schemas /usr/share/glib-2.0/schemas/

--prefix=/usr puts GPaste where the system looks for it: under meson's default /usr/local, distributions like Fedora find neither its libraries nor its typelibs, and the schemas compiled above would be another directory's.

GPaste currently needs GLib 2.90, GTK 4.24, libadwaita 1.10, gcr 4 and Meson 1.9. That libadwaita is newer than anything Debian ships outside experimental, so a deb-based build of the 51 series needs one built by hand.

Build options

Pass these to meson setup (or meson configure build) as -Doption=value. The feature ones default to auto: enabled when the dependency is present, skipped otherwise.

Option	Default	What it controls
encryption	auto	libsodium-based history encryption
sqlite	auto	the SQLite storage backends (needs SQLite ≥ 3.35)
libsecret	auto	remember the encryption passphrase in the keyring (needs encryption)
pwquality	auto	rate a passphrase or a password as it is typed
gnome-shell	true	the GNOME Shell extension and the mutter clipboard backend (requires introspection)
introspection	true	GIR data
vapi	true	Vala bindings (requires introspection)
systemd	true	the systemd user unit
bash-completion, zsh-completion, fish-completion	true	shell completions

For a minimal build:

meson setup build -Dgnome-shell=false -Dintrospection=false -Dvapi=false

Usage

Default shortcuts

Shortcut	Action
Ctrl+Alt+H	Show the history
Ctrl+Alt+G	Launch the graphical tool
Ctrl+Alt+V	Pop the first item off the history
Ctrl+Alt+S	Mark the active item as a password, if it is a text one
Ctrl+Alt+O	Sync the clipboard to the primary selection
Ctrl+Alt+P	Sync the primary selection to the clipboard
Ctrl+Alt+U	Upload the active item to a pastebin, if it is a text one

All of them are configurable in the preferences.

Uploading runs whatever the upload-command preference names, defaulting to curl -sS --data-binary @- https://paste.c-net.org/. Any command that takes the item on its standard input and answers the url on its standard output will do — wgetpaste, pastebinit and nc termbin.com 9999 among them.

Inside the graphical tool, which has a few of its own:

Shortcut	Action
Ctrl+F	Search the history
Ctrl+N	Add a new item
Ctrl+Shift+N	Add a new password
Ctrl+0…9	Paste the item at that index
Delete	Delete the history focused in the sidebar
Ctrl+,	Show the preferences
Ctrl+?	Show the keyboard shortcuts
Ctrl+W or Esc	Close the window
Menu or Shift+F10	Open the selected item's menu

Command line

gpaste-client                       # print the history
gpaste-client --oneline --use-index # ... one line per item, numbered
gpaste-client search <pattern>      # print matching items
gpaste-client select <uuid>         # put an item back in the clipboard
gpaste-client add <text>            # copy some text
echo hello | gpaste-client          # copy from a pipe
gpaste-client file <path>           # copy a file's contents
gpaste-client delete <uuid>         # forget one item
gpaste-client empty                 # forget everything

gpaste-client ui                    # open the graphical tool
gpaste-client preferences           # open the settings
gpaste-client migrate               # switch storage backend
gpaste-client change-passphrase     # re-key an encrypted history
gpaste-client doctor                # check the stored histories, putting right what can be

gpaste-client help lists every subcommand; see also man gpaste-client.

Items are addressed by UUID by default. Pass --use-index to use their position in the history instead, starting at zero: --use-index merge 0 1 2 merges the first three items. Indexes must be unsigned decimal numbers. Text, search patterns, paths and history names keep their usual meaning.

After upgrading

Restart the daemon so the new version takes over:

gpaste-client daemon-reexec
gpaste-client daemon-version   # confirm which one is running

Development

Three libraries are installed, each with its own pkg-config file, headers and GIR, and a VAPI for gpaste-3 and gpaste-gtk4:

Library	pkg-config	GIR	Contents
libgpaste-3	gpaste-3	GPaste-3	Core objects, settings, and the D-Bus client for the daemon
libgpaste-daemon	gpaste-daemon	GPasteDaemon-1	The clipboard item hierarchy, the history and the storage backends
libgpaste-gtk4	gpaste-gtk4	GPasteGtk-4	GTK 4 / libadwaita widgets and helpers

Each has a single umbrella header — <gpaste.h>, <gpaste-daemon.h> and <gpaste-gtk4.h> — which is the only one you may include directly.

Run the test suite from the build directory:

ninja -C build test

Each C test binary runs on its own in-memory settings and private D-Bus, so it needs dbus-daemon; a supervisor reaps that bus even if a test crashes. The UI tests open their windows on a private Xvfb and are skipped without it. The GNOME Shell extension's JavaScript tests (tests/gnome-shell/) run its modules under Node.js with actor and bus doubles: the menu, its rows and their actions, the history switcher, the tracking switch, the storage prompt, the in-shell daemon's runner and the extension's own enable and disable. They are omitted when Node.js is unavailable and touch no settings, bus or display. None of the tests touches the desktop session.

AGENTS.md documents the coding style and repository conventions in more detail, and each part of the tree has an AGENTS.md of its own beside its code.

Contributing

Bug reports and patches are welcome on GitHub.

Translations go through Weblate, which credits every translator on the project page.

GPaste is what a hundred or so people have made it: thanks to everyone who has contributed.

Supporting GPaste

GPaste is developed in my spare time. If it is useful to you, you can support its development through GitHub Sponsors, or through PayPal if you are not on GitHub.

Releases

The latest release for GNOME 51 is GPaste 51.3 (tarball).

Release announcements and everything else about GPaste are on my blog. See NEWS for the full changelog.