pyperclip

1.11.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install pyperclip

Common errors

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

cause 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).

error ModuleNotFoundError: No module named 'pyperclip' ↓

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

fix

Install the library using pip: pip install pyperclip

error NameError: name 'pyperclip' is not defined ↓

cause 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.

Warnings

gotcha On 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`.

gotcha Pyperclip 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.

gotcha When 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.

breaking Recent 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.

gotcha When 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())`.

gotcha The `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()`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 17.8M

3.10 slim (glibc) - - 0.04s 18M

3.11 alpine (musl) - - 0.10s 19.7M

3.11 slim (glibc) - - 0.08s 20M

3.12 alpine (musl) - - 0.04s 11.6M

3.12 slim (glibc) - - 0.07s 12M

3.13 alpine (musl) - - 0.06s 11.2M

3.13 slim (glibc) - - 0.09s 12M

3.9 alpine (musl) - - 0.06s 17.3M

3.9 slim (glibc) - - 0.07s 18M

Imports

pyperclip
```
import pyperclip
```

Quickstart stale last tested: 2026-04-23

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.')