pyperclip

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

• pip install pyperclip

Imports

• pyperclip

  import pyperclip

Quickstart

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