# CopyQ: a scriptable clipboard manager for Linux, Windows and macOS

> CopyQ stores clipboard history in tabs and exposes it through a command line and a scripting API. It suits people who want to automate clipboard handling, and not anyone who wants a single static paste buffer.

**hluk/CopyQ** — Clipboard manager with advanced features

- Repository: https://github.com/hluk/CopyQ
- Stars: 12,325 · Forks: 603
- Language: C++
- License: GPL-3.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/hluk-copyq

## The clipboard problem CopyQ is built around

A system clipboard holds one item. Copy something new and the previous value is gone, which is fine until you are moving text between a terminal, an editor and a browser and need the third value back. CopyQ monitors the system clipboard and saves each new entry into a list, so the history survives the next copy and, according to the README, is restored when CopyQ is next started. Items live in tabs, which means the history can be split by purpose rather than being one long stream. The target user is someone who treats the clipboard as working memory: developers pasting between shells and editors, writers collecting fragments, anyone who has lost a block of text to an accidental copy. It is not aimed at a user who wants the simplest possible paste buffer. The feature list is long on purpose, and every one of those features is something you configure. If you never open the command dialog, you are paying the cost of a Qt application for a list you could get from a lighter tool.

## How the clipboard history mechanism works

CopyQ runs as a background application, usually reached through a system tray icon, and watches the system clipboard. Each copy creates a new item in the current tab. The README states that text, HTML, images and any other custom formats are stored, so an item is not just a string: it can carry several representations of the same copy. That matters when you paste into an application that prefers HTML over plain text, because the stored item can supply the format the target asks for. Items can be edited with F2, removed with Delete, sorted, repositioned with the mouse or Ctrl+Up/Down, copied back with Ctrl+C, and pasted into the previously active window with Enter. Notes and tags can be attached to items, and the README mentions ignoring clipboard content copied from specified windows or containing specified text, which is the mechanism for keeping password managers and similar sources out of the history. Filtering is available when browsing the list. Because the application must be running for the command line to work, the architecture is a client talking to a resident process rather than a standalone binary that reads a file.

## Installing CopyQ and adding your first entry

CopyQ ships as binary packages and installers rather than as a language package, so installation depends on the platform. On Windows the README lists an installer, a portable zip, Scoop from the extras bucket, and Chocolatey. With Scoop installed, the command is:

```bash
scoop install copyq
```

With Chocolatey, the equivalent is:

```bash
choco install copyq
```

On macOS 13 and above, Homebrew installs the cask:

```bash
brew install --cask copyq
```

The README notes that if the app crashes with a dialog saying CopyQ is damaged or cannot be opened, two commands may be needed, referencing issue 2652:

```bash
xattr -d com.apple.quarantine /Applications/CopyQ.app
codesign --force --deep --sign - /Applications/CopyQ.app
```

On Debian 11, Ubuntu 22.04 and derivatives, install the copyq and copyq-plugins packages. The README states the official PPA at ppa:hluk/copyq is no longer maintained, so distribution packages are the path. Fedora and Arch Linux both provide a copyq package. For other distributions there is an AppImage from GitHub Releases:

```bash
chmod +x CopyQ-*.AppImage
./CopyQ-*.AppImage
```

Flatpak is the other option, with com.github.hluk.copyq on Flathub, started with:

```bash
flatpak run com.github.hluk.copyq
```

Once it is running, the history is reachable by clicking the tray icon or by running copyq toggle. The command line is the fastest way to confirm the client can reach the running application. The README gives this example for inserting items directly into the history:

```bash
copyq add -- 'first item' 'second item' 'third item'
```

The double dash matters here. The README warns that omitting -- changes how backslashes in the arguments are interpreted. If the command returns without an error and the three items appear in the list, the client and the resident process are talking to each other. Help for the arguments is available through copyq --help and copyq --help add.

## Custom commands are where CopyQ stops being a list

The command dialog, opened with F6, is the part of CopyQ that has no equivalent in a plain history tool. From there you add a predefined command or write a new one, optionally give it a keyboard shortcut and a name, and save it with OK. Commands can run from the menu, from a shortcut, or when the clipboard changes, which turns the clipboard into an event source rather than just a storage area. The README calls out one predefined command, Show/hide main window, as particularly useful. The scripting interface is documented separately under the scripting API page on readthedocs, and there is a community command repository at hluk/copyq-commands for examples. This is also where the learning curve sits. The README does not attempt to teach the scripting language in the main file; it points to the docs. Anyone evaluating CopyQ purely from the README will see a feature bullet saying advanced scripting and no way to judge how advanced. The honest position is that the command system is the reason to choose CopyQ, and it is also the reason a casual user will find it heavier than expected.

## Where CopyQ is the wrong tool

CopyQ keeps a history of what you copy. That is the whole point and also the risk. The README lists an ignore feature for clipboard content copied from specified windows or containing specified text, which implies the default is to record, and the ignore rules are something you configure rather than something that exists out of the box. A user who copies credentials, tokens or personal data and never sets up those rules is accumulating them in a list that persists across restarts. The README does not document an encryption layer for the stored history, so treat the history as readable by anything that can read your user data. Two other boundaries are worth stating. First, macOS support starts at version 13, tied to the Qt version used, so older Macs are out. Second, CopyQ is a desktop application. There is no Android build in the repository layout or the README, and the cross-platform claim covers Linux, Windows and macOS only. If your work happens on a phone or in a browser-only environment, this is not the tool. Finally, the command line requires the main application to be running, so a headless script cannot use copyq as a standalone utility without the resident process.

## CopyQ against GPaste and Ditto

The two comparisons people search for are GPaste and Ditto, and they differ from CopyQ in ways that matter more than feature counts. GPaste is a GNOME-oriented clipboard manager, which means it is built to live inside that desktop's shell and settings rather than as a cross-desktop application with its own window, tray icon and command dialog. If your desktop is GNOME and you want the clipboard handled by the desktop, GPaste is the shorter path; if you want the same behaviour on Windows and macOS as well, CopyQ is the one that ships for all three. Ditto is the Windows-side comparison. It is a Windows clipboard manager, so the difference is reach: CopyQ's command line and scripting interface are documented as a first-class part of the application, while Ditto's scope is Windows. Neither comparison should be settled by a feature list. The question to ask is whether you will actually write commands and shortcuts, because that is what CopyQ charges you for in complexity, and if the answer is no, a desktop-integrated manager will do the same job with less to configure.

## Licence, maintenance and upgrade cost

CopyQ is licensed under GPL-3.0, and the repository carries both LICENSE and gpl.txt at the top level. For individual desktop use this is unremarkable. For anyone embedding CopyQ in a product, the copyleft terms of GPL-3.0 apply to distribution, and that is a question for your own legal review rather than something to settle from a README. On maintenance, the repository is not archived and the last push was on 2026-09-20, so the project is being worked on now. The release cadence is tight: v14.0.0 on 2026-03-24, v15.0.0 on 2026-04-12 and v16.0.0 on 2026-05-30. Three major versions in roughly two months is worth noting if you pin versions, because major numbers moving that quickly usually means breaking changes somewhere. The upgrade cost is mostly on the packaging side: the README states the Ubuntu PPA is no longer maintained, so Ubuntu users should track distribution packages or move to the AppImage or Flatpak build. The repository also carries a .pre-commit-config.yaml and a pyproject.toml that configures codespell for the source tree, which is a maintenance detail rather than something an end user touches.

## Conclusion

Adopt CopyQ if you want clipboard history you can script: the command line and the F6 command dialog are the reason to pick it over a static paste buffer. Skip it if you only need one remembered item, or if you are on macOS older than 13, which the README lists as the floor. Before relying on it, verify two things on your own machine: that copyq add returns without error while the GUI is running, and that your distribution still ships the copyq and copyq-plugins packages, since the Ubuntu PPA ppa:hluk/copyq is no longer maintained.

## FAQ

### How does CopyQ work?

CopyQ runs in the background, monitors the system clipboard and saves each new entry into a list organized in tabs. Items can be edited, sorted, repositioned, copied back to the clipboard or pasted into the previously active window, and the history is restored when CopyQ is next started.

### Is CopyQ safe to use?

The README does not document encryption for the stored history, so items you copy are kept in a list that persists across restarts. CopyQ can ignore clipboard content copied from specified windows or containing specified text, but those rules are something you configure rather than defaults.

### How do I install CopyQ?

Installation depends on the platform. Windows has an installer, a portable zip, Scoop and Chocolatey; macOS 13 and above uses brew install --cask copyq; Debian, Ubuntu, Fedora and Arch provide a copyq package; other Linux distributions can use the AppImage or the Flatpak build com.github.hluk.copyq.

### How do I use CopyQ on Ubuntu?

Install the copyq and copyq-plugins packages from your distribution. The README states the official PPA ppa:hluk/copyq is no longer maintained, so distribution packages, the AppImage or Flatpak are the options. Start the app, then use copyq toggle or the tray icon to open the history.

### What is a good clipboard manager for Linux?

CopyQ supports Linux, Windows and macOS 13 and above, and stores text, HTML, images and other custom formats in tabs. It also exposes a command line and a scripting interface, which distinguishes it from desktop-integrated managers such as GPaste.

## Sources

- [hluk/CopyQ on GitHub](https://github.com/hluk/CopyQ)
- [Issues](https://github.com/hluk/CopyQ/issues)
- [License: GPL-3.0](https://github.com/hluk/CopyQ/blob/master/LICENSE)
- [README](https://github.com/hluk/CopyQ/blob/master/README.md)
- [Releases](https://github.com/hluk/CopyQ/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hluk-copyq