pyperclip

library1.11.0pypypi✓ verified 27d ago

Pyperclip is a cross-platform Python module (current version 1.11.0) for copying and pasting plain text to and from the clipboard. It provides a simple API (`copy()` and `paste()`) and is actively maintained with regular updates, enabling clipboard interaction across Windows, macOS, and Linux.

serialization

pip install pyperclip

github ↗package ↗

INSTALL

IMPORT

SIG · PYPERCLIP

pyperclip

serializationpythonv1.11.0

Install

1.6s avg

Import

43ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.11.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.040s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.046s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pyperclip

✓ import pyperclip

This quickstart demonstrates basic text copying and pasting using `pyperclip.copy()` and `pyperclip.paste()`. It also includes commented-out code for `pyperclip.waitForNewPaste()` to illustrate waiting for new clipboard content, handling a timeout gracefully.

import pyperclip text_to_copy = 'Hello, world! This is copied by pyperclip.' pyperclip.copy(text_to_copy) print(f'Copied: "{text_to_copy}" to clipboard.') pasted_text = pyperclip.paste() print(f'Pasted: "{pasted_text}" from clipboard.') # Example of waiting for new paste (requires manual paste action by user) # print('Waiting for a new paste (max 5 seconds)...') # try: # new_paste = pyperclip.waitForNewPaste(timeout=5) # print(f'New text pasted: "{new_paste}"') # except pyperclip.PyperclipTimeoutException: # print('No new paste detected within 5 seconds.')

Debug

Known issues

gotchaOn Linux, `pyperclip` may raise a 'Pyperclip could not find a copy/paste mechanism' error. This typically means required command-line utilities (like `xclip`, `xsel`, or `wl-clipboard`) or Python modules (like `PyQt5`, `PyQt4`, or `gtk`) are not installed.

fix

Install one of the required system utilities or Python modules. E.g., `sudo apt-get install xclip` or `pip install PyQt5`.

affects: All versions

gotchaPyperclip only handles plain text. If you copy images or rich text, `pyperclip.paste()` will return an empty string or plain text representation if available.

fix

Use libraries like `pyperclipimg` (a separate module) or Pillow's `ImageGrab` for image-specific clipboard operations.

affects: All versions

gotchaWhen running `pyperclip` in a remote server environment (e.g., Streamlit Cloud, Docker containers, WSL2), it interacts with the *server's* clipboard, not the client's local clipboard. This can lead to unexpected behavior or `FileNotFoundError` (e.g., `clip.exe` not found).

fix

Be aware of the execution environment. For client-side clipboard interaction in web apps, client-side JavaScript solutions are typically required. For Docker/WSL, ensure necessary X server/display settings are configured if GUI clipboard access is truly needed.

affects: All versions

breakingRecent versions (1.9.0, 1.10.0, 1.11.0) have dropped or broken Python 2 compatibility due to updated dependencies or syntax. The library is now primarily Python 3 focused.

fix

Ensure you are running Python 3.x. If Python 2 compatibility is strictly required, pin to an older `pyperclip` version (e.g., <1.9.0) at your own risk, or migrate your application to Python 3.

affects: >=1.9.0

gotchaWhen copying text from files or other sources, ensure to strip any unintended line breaks (e.g., `\n`, `\r`) before passing to `pyperclip.copy()`. Including these can lead to incorrectly formatted paths or text when pasted into other applications.

fix

Use string methods like `.strip()` or `.replace('\n', '')` to clean the text before copying: `pyperclip.copy(my_text.strip())`.

affects: All versions

gotchaThe `pyperclip.paste()` function does not take any arguments. Passing an argument to `paste()` (e.g., `pyperclip.paste('some text')`) will result in a `TypeError`.

fix

Call `pyperclip.paste()` without any arguments: `pasted_content = pyperclip.paste()`.

affects: All versions

Errors

Common errors & fixes

PyperclipException: Can't find clipboard tools for xsel or xclip. Please install one of these or an equivalent tool.

On Linux and WSL environments, pyperclip requires external command-line utilities like `xclip` or `xsel` to interact with the clipboard, which are not installed by default.

fix

Install `xclip` or `xsel` using your package manager (e.g., `sudo apt-get install xclip` or `sudo apt-get install xsel` on Debian/Ubuntu-based systems).

ModuleNotFoundError: No module named 'pyperclip'

The `pyperclip` library has not been installed in the Python environment you are currently using.

fix

Install the library using pip: `pip install pyperclip`

NameError: name 'pyperclip' is not defined

The `pyperclip` module has been installed but was not imported into your Python script or interactive session before being used.

fix

Add `import pyperclip` at the beginning of your Python script or before using any `pyperclip` functions.

Upgrade

Version history

1.11.0latest on PyPI · released Sep 26, 2025

Audit

Dependencies

xclipoptionalRequired for clipboard functionality on some Linux distributions (CLI utility).

xseloptionalRequired for clipboard functionality on some Linux distributions (CLI utility).

wl-clipboardoptionalRequired for clipboard functionality on Wayland sessions (CLI utility).

PyQt5optionalFallback for clipboard functionality on some Linux distributions (Python module).

PyQt4optionalFallback for clipboard functionality on some Linux distributions (Python module).

gtkoptionalFallback for clipboard functionality on some Linux distributions (Python module).

pyobjcoptionalUsed for clipboard functionality on macOS.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/asweigart/pyperclip ↗

packagehttps://pypi.org/project/pyperclip/ ↗