copykitten

A robust, dependency-free way to use the system clipboard in Python.

Installation

copykitten supports Python >= 3.8.

You can install copykitten from PyPI using pip or any other Python package manager.

pip install copykitten

Usage

Text

To copy or paste text content, use copykitten.copy and copykitten.paste functions.

import copykitten

copykitten.copy("The kitten says meow")

import copykitten

text = copykitten.paste()

Image

To copy or paste images, use copykitten.copy_image and copykitten.paste_image functions. Working with images is a bit complex, so read further.

import copykitten
from PIL import Image

image = Image.open("image.png")
pixels = image.tobytes()

copykitten.copy_image(pixels, image.width, image.height)

import copykitten
from PIL import Image

pixels, width, height = copykitten.paste_image()
image = Image.frombytes(mode="RGBA", size=(width, height), data=pixels)
image.save("image.png")

To copy an image to the clipboard, you have to pass three arguments - pixel data, width, and height. Pixel data must be a bytes object containing the raw RGBA value for each pixel. You can easily get it using an imaging library like Pillow.

If your image is not of RGBA type (like a typical JPEG, which is RGB), you first have to convert it to RGBA, otherwise copy_image will raise an exception.

When pasting an image from the clipboard you will receive a 3-tuple of (pixels, width, height). Pixels here are the same RGBA bytes object. Please note that it is not guaranteed that any image copied to the clipboard by another program will be successfully pasted with copykitten.

You can read more about the data format and the implications of working with images in the arboard documentation.

Clear

To clear the clipboard, use copykitten.clear function.

import copykitten

copykitten.clear()

File paths

To copy or paste file paths, use copykitten.copy_paths and copykitten.paste_paths functions.

import copykitten
import pathlib

copykitten.copy_paths('/home/user/.bashrc') # Copy one path.
copykitten.copy_paths('/home/user/.bashrc', '/home/user/.bash_aliases') # Or multiple.
copykitten.copy_paths(pathlib.Path('C://Users/user/file.txt'))  # Or a pathlib.Path.

import copykitten

paths = copykitten.paste_paths()

Note that the files you are about to copy into the clipboard must exist, otherwise an exception will be raised.

Detach mode

Both copy and copy_image functions support an optional keyword-only bool parameter detach (defaults to False). This feature is only relevant on Linux; using it on Windows or macOS is a no-op.

import copykitten
from PIL import Image

# Copy text with detach.
copykitten.copy("meow", detach=True)

# Copy image with detach.
image = Image.open("image.png")
image_bytes = image.tobytes()
copykitten.copy_image(image_bytes, image.width, image.height, detach=True)

Copying with detach will spawn a background process (a daemon) that will manage the copied content instead of the parent process. This is useful for one-off scripts that copy something to the clipboard and exit shortly after that. In this case, the copied content may become unavailable; there will be nothing to paste. A lot of times, this is not a problem due to Linux distros including a pre-installed clipboard manager that will handle such cases. Still, some distros don't have a clipboard manager.

The background process will run until the clipboard content is overwritten by another copy operation.

Knows issues

For now, there are some limitations that arise from the way the daemon is spawned (namely, as a fork of the parent process).

1. Interleaving copying w/o detach and with detach (during the execution of a single program) won't work well and may lead to a paste attempt freezing the application until the clipboard is overwritten. Choose one way and stick to it.
2. If your program utilizes large amounts of memory, this memory won't be freed until the background process exit.

Rationale

At the time of writing, there are very few Python packages that handle the clipboard. Most of them are simply no longer maintained (including the most popular solution around the web, pyperclip).

They all depend on external command-line tools like xclip/pbcopy or libraries like PyQt/GTK. You have to make sure these dependencies are installed on the target machine, otherwise they won’t work.

There are some solutions using the Tkinter library, which comes with the standard Python suite. However, these solutions are fragile and may leave your app unresponsive.

Copykitten is a lightweight wrapper around the Rust arboard library. It comes with pre-built wheels for Linux (x64, ARM64), macOS (x64, ARM64), and Windows (x64), so you don't have to worry about anything.

What's in a name?

You can’t even imagine, how many Python packages devoted to the clipboard management there are on PyPI! Most of them are abandoned for a decade, and all the neat obvious names (and even some rather creative ones) are already taken. So I had no choice, but to take this tongue-in-cheek name. Also, my wife approved it.