pyperclip Documentation

Pyperclip is cross-platform and works on Windows, Mac, and Linux.

Unsupported Environments:

• Mobile operating systems (Android, iOS).
• Browser-based interactive shells (e.g., replit.com, pythontutor.com, pythonanywhere.com).

Pyperclip provides a simple API for clipboard interaction. Note that it currently only handles plaintext.

• Use pyperclip.copy(text) to send a string to the clipboard.
• Use pyperclip.paste() to retrieve the current string from the clipboard.

Install the module using pip depending on your operating system and Python version:

• Windows: pip install pyperclip
• Linux/macOS: pip3 install pyperclip

Pyperclip requires external utilities on Linux to function. Depending on your display server and preference, install one of the following via your package manager:

For X11 sessions:

• xclip
• xsel

For Wayland sessions:

• wl-clipboard

Alternative (Qt):

• qtpy or PyQt5

Example for Debian/Ubuntu:

sudo apt-get install xclip
sudo apt-get install xsel
sudo apt-get install wl-clipboard

If you encounter an error stating that Pyperclip could not find a copy/paste mechanism, it is likely because you are on Linux and missing a required system utility or Python module. You can resolve this by installing one of the following:

System Utilities (X11 or Wayland):

• sudo apt-get install xsel (for X11)
• sudo apt-get install xclip (for X11)
• sudo apt-get install wl-clipboard (for Wayland)

Python Modules:

• pip install gtk
• pip install PyQt5

Pyperclip provides two blocking functions to monitor the clipboard:

• pyperclip.waitForPaste(): Blocks execution until the clipboard contains a non-empty string. Returns that string.
• pyperclip.waitForNewPaste(): Blocks execution until the text on the clipboard changes from its current value.

Both functions accept an optional timeout argument (in seconds). If the condition is not met within the timeout period, a pyperclip.PyperclipTimeoutException is raised.

Pyperclip relies on system-level tools to function. Depending on your OS, you may need to install additional dependencies:

• Windows: No additional modules are needed.
• macOS: Uses pbcopy and pbpaste (included with the OS).
• Linux:
  • Requires either xclip or xsel. You can install them via:
    • sudo apt-get install xclip
    • sudo apt-get install xsel (Note: xsel may be unreliable).
  • Alternatively, you can use the qtpy or PyQT5 Python modules.

You can manually override the automatic clipboard detection by calling pyperclip.set_clipboard(mechanism). This is useful if you want to avoid heavy dependencies (like PyQt5) or if the automatic detection fails.

Supported mechanisms:

• pbcopy (Mac OS X)
• pyobjc (Mac OS X)
• qt (Cross-platform via qtpy/PyQt5)
• xclip (Linux)
• xsel (Linux)
• wl-clipboard (Linux Wayland)
• klipper (Linux KDE)
• windows (Windows)
• no (Disables clipboard)

Use pyperclip.is_available() to check if the module successfully found a compatible clipboard mechanism for your current operating system and environment. It returns True if copy/paste functions are ready, and False otherwise.

import pyperclip
if not pyperclip.is_available():
    print("Copy functionality unavailable!")

Use pyperclip.copy(text) to copy a string to the system clipboard. The function handles the underlying OS-specific mechanism automatically.

import pyperclip
pyperclip.copy('The text to be copied to the clipboard.')

Use pyperclip.paste() to retrieve the current contents of the system clipboard as a string.

import pyperclip
spam = pyperclip.paste()

When clipboard operations fail, Pyperclip may raise the following exceptions:

• PyperclipException: The base exception for all Pyperclip errors.
• PyperclipWindowsException: Raised when a Windows-specific clipboard error occurs (includes Windows error details).
• PyperclipTimeoutException: Raised when a clipboard operation times out.