{"id":565,"library":"pyperclip","title":"pyperclip","description":"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.","status":"active","version":"1.11.0","language":"python","source_language":"en","source_url":"https://github.com/asweigart/pyperclip","tags":["clipboard","copy","paste","cross-platform","automation","text"],"install":[{"cmd":"pip install pyperclip","lang":"bash"}],"dependencies":[{"reason":"Required for clipboard functionality on some Linux distributions (CLI utility).","package":"xclip","optional":true},{"reason":"Required for clipboard functionality on some Linux distributions (CLI utility).","package":"xsel","optional":true},{"reason":"Required for clipboard functionality on Wayland sessions (CLI utility).","package":"wl-clipboard","optional":true},{"reason":"Fallback for clipboard functionality on some Linux distributions (Python module).","package":"PyQt5","optional":true},{"reason":"Fallback for clipboard functionality on some Linux distributions (Python module).","package":"PyQt4","optional":true},{"reason":"Fallback for clipboard functionality on some Linux distributions (Python module).","package":"gtk","optional":true},{"reason":"Used for clipboard functionality on macOS.","package":"pyobjc","optional":true}],"imports":[{"symbol":"pyperclip","correct":"import pyperclip"}],"quickstart":{"code":"import pyperclip\n\ntext_to_copy = 'Hello, world! This is copied by pyperclip.'\npyperclip.copy(text_to_copy)\nprint(f'Copied: \"{text_to_copy}\" to clipboard.')\n\npasted_text = pyperclip.paste()\nprint(f'Pasted: \"{pasted_text}\" from clipboard.')\n\n# Example of waiting for new paste (requires manual paste action by user)\n# print('Waiting for a new paste (max 5 seconds)...')\n# try:\n#     new_paste = pyperclip.waitForNewPaste(timeout=5)\n#     print(f'New text pasted: \"{new_paste}\"')\n# except pyperclip.PyperclipTimeoutException:\n#     print('No new paste detected within 5 seconds.')","lang":"python","description":"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."},"warnings":[{"fix":"Install one of the required system utilities or Python modules. E.g., `sudo apt-get install xclip` or `pip install PyQt5`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use libraries like `pyperclipimg` (a separate module) or Pillow's `ImageGrab` for image-specific clipboard operations.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"Use string methods like `.strip()` or `.replace('\\n', '')` to clean the text before copying: `pyperclip.copy(my_text.strip())`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Call `pyperclip.paste()` without any arguments: `pasted_content = pyperclip.paste()`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T15:11:15.362Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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).","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.","error":"PyperclipException: Can't find clipboard tools for xsel or xclip. Please install one of these or an equivalent tool."},{"fix":"Install the library using pip: `pip install pyperclip`","cause":"The `pyperclip` library has not been installed in the Python environment you are currently using.","error":"ModuleNotFoundError: No module named 'pyperclip'"},{"fix":"Add `import pyperclip` at the beginning of your Python script or before using any `pyperclip` functions.","cause":"The `pyperclip` module has been installed but was not imported into your Python script or interactive session before being used.","error":"NameError: name 'pyperclip' is not defined"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"17.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2,"disk_size":"19.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2,"disk_size":"11.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.1,"disk_size":"11.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":1.9,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.6,"disk_size":"17.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":1.6,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}