pyperclip

pyperclip gives Python programs a single, portable way to read and write the operating system clipboard. Instead of writing separate code paths for Windows, macOS, and Linux, a script just calls pyperclip.copy(text) and pyperclip.paste(), and the module figures out at runtime which underlying mechanism to use — direct Win32 API calls via ctypes on Windows, the pbcopy/pbpaste commands (or pyobjc) on macOS, and xclip, xsel, wl-clipboard, or klipper on Linux.

Because it ships with no required third-party dependencies and detects its backend lazily on first use, pyperclip is a common building block in CLI tools, automation scripts, and testing utilities that need to interact with the clipboard without pulling in a GUI toolkit.

What You Get

• copy() / paste() - the entire public surface for clipboard interaction, working identically across Windows, macOS, and Linux
• Automatic backend detection - determine_clipboard() inspects the OS, environment variables (DISPLAY, WAYLAND_DISPLAY), and installed executables to pick the right implementation with no configuration
• Lazy loading - the real backend isn’t selected until copy() or paste() is first called, so importing pyperclip never pulls in a heavyweight GUI toolkit like PyQt5 unintentionally
• set_clipboard() override - lets callers force a specific backend (pbcopy, xclip, xsel, qt, windows, etc.) instead of relying on auto-detection
• is_available() check - lets a program detect at runtime whether any clipboard mechanism was found before attempting to use it
• CLI entry point - python -m pyperclip --copy/--paste exposes the same functionality from the command line or shell pipelines

Common Use Cases

• CLI tool output - a command-line tool copies its result (a generated token, formatted snippet, or URL) straight to the user’s clipboard for immediate pasting
• Test automation - test suites read or seed clipboard contents to verify copy/paste behavior in GUI or terminal applications
• Data entry scripts - automation scripts read structured data, format it, and place it on the clipboard for a human to paste into another application
• Cross-platform utilities - developers building tools that must run identically on Windows, macOS, and Linux use pyperclip instead of writing three separate clipboard integrations

Under The Hood

Architecture The entire module lives in a single file (src/pyperclip/__init__.py, ~660 lines) organized around a strategy pattern: a family of init_*_clipboard() functions (init_osx_pbcopy_clipboard, init_xclip_clipboard, init_windows_clipboard, init_qt_clipboard, and others) each return a (copy, paste) function pair for one backend. determine_clipboard() inspects platform.system(), os.name, environment variables like DISPLAY and WAYLAND_DISPLAY, and executable availability via shutil.which() to pick the winning pair, which is then bound to the module-level copy/paste names. Lazy-loading stub functions (lazy_load_stub_copy/lazy_load_stub_paste) defer this detection until the first actual call, so importing the module never triggers a heavyweight dependency load (e.g. PyQt5) unless the caller actually copies or pastes.

Tech Stack pyperclip has no required third-party dependencies — it relies entirely on the Python standard library (ctypes, subprocess, contextlib, shutil.which). On Windows it drives the Win32 API directly through ctypes (OpenClipboard, GlobalAlloc, SetClipboardData against user32/kernel32); on macOS it shells out to the built-in pbcopy/pbpaste commands, or uses pyobjc’s Foundation/AppKit modules if they happen to be installed; on Linux it shells out to xclip, xsel, wl-copy/wl-paste, or klipper via qdbus, with an optional fallback to qtpy/PyQt5 bindings. Packaging uses setuptools with the version read dynamically from __version__, and the test matrix is defined in tox.ini and Pipfile.

Code Quality tests/test_pyperclip.py defines a shared _TestClipboard unittest base class exercising each backend for copy/paste round-trips, unicode and emoji handling, whitespace, and blank strings, with per-mechanism subclasses that skip themselves when a given backend isn’t available on the test machine. Error handling is explicit rather than silent: pyperclip defines its own exception hierarchy (PyperclipException, PyperclipWindowsException, PyperclipTimeoutException) instead of swallowing subprocess or ctypes failures. Naming is plain snake_case throughout with a module-level docstring documenting exactly which external executables are shelled out to and why — an unusually transparent security note about that trust boundary. No CI configuration or linter/formatter setup is present in the repository, and type hints are limited (a couple of unused Union/Optional imports remain from an earlier typing pass).

API Design The public API is deliberately minimal — two functions, copy() and paste() — that work with zero configuration across three operating systems, which is the module’s main developer-experience win: callers never need to know or care which backend is in play. is_available() and set_clipboard() provide clean escape hatches for programs that need to check clipboard support or force a specific mechanism, without adding any ceremony to the common case. The extensive top-of-file docstring doubles as both usage documentation and a security disclosure, which is a level of transparency about subprocess trust boundaries that’s uncommon for a utility this small.