0
# Pyperclip
1

2
A cross-platform clipboard module for Python that provides simple clipboard functionality for copying and pasting plain text across Windows, macOS, and Linux systems. The library automatically detects the operating system and uses the appropriate clipboard mechanism with zero configuration required.
3

4
## Package Information
5

6
- **Package Name**: pyperclip
7
- **Package Type**: pypi
8
- **Language**: Python  
9
- **Installation**: `pip install pyperclip`
10
- **Platforms**: Windows, macOS, Linux, WSL
11
- **Python Versions**: 2.7, 3.5+
12

13
## Core Imports
14

15
```python
16
import pyperclip
17
```
18

19
## Basic Usage
20

21
```python
22
import pyperclip
23

24
# Copy text to clipboard
25
pyperclip.copy('Hello, World!')
26

27
# Paste text from clipboard  
28
text = pyperclip.paste()
29
print(text)  # Hello, World!
30

31
# Check if clipboard functionality is available
32
if pyperclip.is_available():
33
    pyperclip.copy('Clipboard is working!')
34
else:
35
    print('Clipboard functionality unavailable!')
36
```
37

38
## Architecture
39

40
Pyperclip uses a platform detection system with automatic fallback mechanisms:
41

42
- **Windows**: Native Windows API via ctypes
43
- **macOS**: PyObjC (preferred) or pbcopy/pbpaste commands  
44
- **Linux**: Multiple mechanisms with automatic fallback (GTK, Qt, xclip, xsel, wl-clipboard, KDE Klipper)
45
- **WSL**: Windows clipboard integration
46
- **Cygwin**: /dev/clipboard (limited support)
47

48
The library uses lazy loading - clipboard mechanisms are only initialized when first accessed, allowing users to explicitly set preferred mechanisms via `set_clipboard()` before first use.
49

50
## Capabilities
51

52
### Text Operations
53

54
Copy and paste plain text to/from the system clipboard with automatic type conversion and cross-platform compatibility.
55

56
```python { .api }
57
def copy(text):
58
    """
59
    Copy text to the clipboard.
60
    
61
    Args:
62
        text: Text to copy. Accepts str, int, float, bool - non-str values are converted to str.
63
        
64
    Returns:
65
        None
66
        
67
    Raises:
68
        PyperclipException: If text is None or other invalid types like lists/dicts
69
        PyperclipWindowsException: Windows-specific clipboard errors
70
        PyperclipTimeoutException: Timeout errors during clipboard access
71
    """
72

73
def paste():
74
    """
75
    Retrieve text from the clipboard.
76
    
77
    Returns:
78
        str: Text content from clipboard, empty string if clipboard is empty
79
        
80
    Raises:
81
        PyperclipException: If clipboard functionality is unavailable
82
        PyperclipWindowsException: Windows-specific clipboard errors  
83
        PyperclipTimeoutException: Timeout errors during clipboard access
84
    """
85
```
86

87
### Clipboard Configuration
88

89
Explicitly control which clipboard mechanism to use and detect available functionality.
90

91
```python { .api }
92
def set_clipboard(clipboard):
93
    """
94
    Explicitly set the clipboard mechanism.
95
    
96
    Args:
97
        clipboard (str): Clipboard mechanism name. Valid values:
98
            'pbcopy' - macOS pbcopy/pbpaste commands
99
            'pyobjc' - macOS PyObjC (default on macOS)  
100
            'gtk' - Linux GTK clipboard
101
            'qt' - Linux Qt clipboard (PyQt4/PyQt5/qtpy)
102
            'xclip' - Linux xclip command
103
            'xsel' - Linux xsel command
104
            'wl-clipboard' - Linux wl-clipboard (Wayland)
105
            'klipper' - Linux KDE Klipper via qdbus
106
            'windows' - Windows API (default on Windows)
107
            'no' - Disable clipboard (raises exceptions)
108
            
109
    Returns:
110
        None
111
        
112
    Raises:
113
        ValueError: If invalid clipboard mechanism specified
114
    """
115

116
def determine_clipboard():
117
    """
118
    Automatically determine and set the appropriate clipboard mechanism for current platform.
119
    
120
    Returns:
121
        tuple: (copy_function, paste_function) - The selected clipboard functions
122
    """
123

124
def is_available():
125
    """
126
    Check if clipboard functionality is available.
127
    
128
    Returns:
129
        bool: True if clipboard is available, False if clipboard is disabled or unavailable
130
    """
131
```
132

133
### Command Line Interface
134

135
Access clipboard functionality from the command line using the module's CLI.
136

137
```bash
138
# Copy text to clipboard
139
python -m pyperclip --copy "Text to copy"
140
python -m pyperclip -c "Text to copy"
141

142
# Copy from stdin
143
echo "Text from stdin" | python -m pyperclip --copy
144
python -m pyperclip -c < file.txt
145

146
# Paste from clipboard to stdout  
147
python -m pyperclip --paste
148
python -m pyperclip -p
149
```
150

151
## Types
152

153
```python { .api }
154
class PyperclipException(RuntimeError):
155
    """Base exception for pyperclip-related errors."""
156

157
class PyperclipWindowsException(PyperclipException):
158
    """Windows-specific clipboard errors with Windows error codes."""
159

160
class PyperclipTimeoutException(PyperclipException):
161
    """Timeout errors during clipboard access."""
162
```
163

164
## Constants
165

166
```python { .api }
167
__version__ = '1.9.0'  # Library version
168
ENCODING = 'utf-8'     # Text encoding used for clipboard operations
169
```
170

171
## Usage Examples
172

173
### Basic Text Handling
174

175
```python
176
import pyperclip
177

178
# Copy various data types (auto-converted to strings)
179
pyperclip.copy(42)          # Copied as '42'  
180
pyperclip.copy(3.14159)     # Copied as '3.14159'
181
pyperclip.copy(True)        # Copied as 'True'
182

183
# Multi-line text handling
184
multiline_text = """Line 1
185
Line 2  
186
Line 3"""
187
pyperclip.copy(multiline_text)
188
pasted = pyperclip.paste()
189
print(repr(pasted))  # Preserves newlines
190

191
# Unicode support
192
pyperclip.copy('Hello 世界 🌍')
193
print(pyperclip.paste())  # Hello 世界 🌍
194
```
195

196
### Platform-Specific Configuration
197

198
```python
199
import pyperclip
200

201
# Explicitly set clipboard mechanism (useful for servers/containers)
202
pyperclip.set_clipboard('xclip')  # Force xclip on Linux
203
pyperclip.copy('Using xclip specifically')
204

205
# Check availability before use
206
if not pyperclip.is_available():
207
    print("Install xclip, xsel, or wl-clipboard for Linux clipboard support")
208
else:
209
    pyperclip.copy("Clipboard is working!")
210
```
211

212
### Error Handling
213

214
```python
215
import pyperclip
216

217
try:
218
    # These will raise PyperclipException
219
    pyperclip.copy(None)        # Invalid type
220
    pyperclip.copy([1, 2, 3])   # Invalid type
221
except pyperclip.PyperclipException as e:
222
    print(f"Clipboard error: {e}")
223

224
# Platform-specific error handling
225
try:
226
    pyperclip.copy("Test")
227
except pyperclip.PyperclipWindowsException as e:
228
    print(f"Windows clipboard error: {e}")
229
except pyperclip.PyperclipTimeoutException as e:
230
    print(f"Clipboard timeout: {e}")
231
```