pyclipx 0.8.0

Cross-platform clipboard utilities supporting both binary and text data.

PyClipX

Cross-platform clipboard utilities supporting both binary and text data.

This is a fork of the original PyClip project, maintained under Apache License 2.0. All functionality remains compatible with the original API.

Why PyClipX?

This fork was created to fix clipboard compatibility issues when running with sudo on Ubuntu 26.04 LTS and other modern Linux distributions that use pure Wayland as the display server. While the original PyClip project works fine in non-root environments, it encounters issues when run with elevated privileges. This version focuses on:

• Sudo compatibility - fixes clipboard operations when running with sudo privileges on Wayland
• Enhanced Wayland support through the wayland_clip.py module, which provides clipboard functionality via wl-copy/wl-paste commands
• Modern Linux compatibility for systems that have moved away from X11 to Wayland

The wayland_clip.py module specifically handles clipboard operations on Wayland by leveraging the wl-clipboard package, which is the standard Wayland clipboard utility.

Some key features include:

• A cross-platform API (supports MacOS, Windows, Linux)
• Can handle arbitrary binary data
• On Windows, some additional clipboard formats are supported

Installation

Requires python 3.7+

pip install pyclipx

Usage

pyclip can be used in Python code

import pyclip

pyclip.copy("hello clipboard") # copy data to the clipboard
cb_data = pyclip.paste() # retrieve clipboard contents 
print(cb_data)  # b'hello clipboard'
cb_text = pyclip.paste(text=True)  # paste as text
print(cb_text)  # 'hello clipboard'

pyclip.clear() # clears the clipboard contents
assert not pyclip.paste()

Note: When running with sudo on Wayland (e.g., Ubuntu 26.04 LTS), pyclipx automatically detects the sudo environment and sets the necessary Wayland environment variables (WAYLAND_DISPLAY and XDG_RUNTIME_DIR) for you. No manual configuration is needed.

Or a CLI

# paste clipboard contents to stdout
python -m pyclip paste

# load contents to the clipboard from stdin
python -m pyclip copy < myfile.text
# same as above, but pipe from another command
some-program | python -m pyclip copy

Installing via pip also provides the console script pyclip:

pyclip copy < my_file.txt

This library implements functionality for several platforms and clipboard utilities.

• MacOS
• Windows
• Linux on x11 (with xclip)
• Linux on wayland (with wl-clipboard)

If there is a platform or utility not currently listed, please request it by creating an issue.

Platform specific notes/issues

Windows

• On Windows, the pywin32 package is installed as a requirement.
• On Windows, additional clipboard formats are supported, including copying from a file (like if you right-click copy from File Explorer)

MacOS

MacOS has support for multiple backends. By default, the pasteboard package is used.

pbcopy/pbpaste can also be used as a backend, but does not support arbitrary binary data, which may lead to data being lost on copy/paste. This backend may be removed in a future release.

Linux

Linux on X11 requires xclip to work. Install with your package manager, e.g. sudo apt install xclip Linux on Wayland requires wl-clipboard to work. Install with your package manager, e.g. sudo apt install wl-clipboard

Acknowledgements

Big thanks to Howard Mao for donating the PyClip project name on PyPI to the original project.