Welcome to the documantation for pyclip!

To get started:

pip install pyclip

Requires Python 3.7+

PyClip

Cross-platform clipboard utilities supporting both binary and text data.

Some key features include:

• A cross-platform API (supports MacOS, Windows, Linux)

• Can handle arbitrary binary data

• On Windows, some additional clipboard formats are supported

Installation

Requires python 3.7+

pip install pyclip

Usage

pyclip can be used in Python code

import pyclip

pyclip.copy("hello clipboard") # copy data to the clipboard
cb_data = pyclip.paste() # retrieve clipboard contents
print(cb_data)  # b'hello clipboard'
cb_text = pyclip.paste(text=True)  # paste as text
print(cb_text)  # 'hello clipboard'

pyclip.clear() # clears the clipboard contents
assert not pyclip.paste()

Or a CLI

# paste clipboard contents to stdout
python -m pyclip paste

# load contents to the clipboard from stdin
python -m pyclip copy < myfile.text
# same as above, but pipe from another command
some-program | python -m pyclip copy

Installing via pip also provides the console script pyclip:

pyclip copy < my_file.txt

This library implements functionality for several platforms and clipboard utilities.

• [x] MacOS

• [x] Windows

• [x] Linux on x11 (with xclip)

• [x] Linux on wayland (with wl-clipboard)

If there is a platform or utility not currently listed, please request it by creating an issue.

Platform specific notes/issues

Windows

• On Windows, the pywin32 package is installed as a requirement.

• On Windows, additional clipboard formats are supported, including copying from a file (like if you right-click copy from File Explorer)

MacOS

MacOS has support for multiple backends. By default, the pasteboard package is used.

pbcopy/pbpaste can also be used as a backend, but does not support arbitrary binary data, which may lead to data being lost on copy/paste. This backend may be removed in a future release.

Linux

Linux on X11 requires xclip to work. Install with your package manager, e.g. sudo apt install xclip Linux on Wayland requires wl-clipboard to work. Install with your package manager, e.g. sudo apt install wl-clipboard

Acknowledgements

Big thanks to Howard Mao for donating the PyClip project name on PyPI to this project.

PyClip API

To support multiple platforms, PyClip’s API is composed of several implementations.

Generally, the public API is provided by __init__.py:

__init__.py

pyclip.__init__.clear(*args, **kwargs)

pyclip.__init__.copy(*args, **kwargs)

pyclip.__init__.paste(*args, **kwargs)

pyclip.__init__.wrapif(f)

Here you will find auto-generated API docs for modules contained herein. Loosely, each platform implementation will have its own module.

The base class from which all implementations are derived is in the pyclip.base module.

pyclip base module

Provides the abstract base class from which all clipboard implementations are derived.

class pyclip.base.ClipboardBase

Abstract base class for Clipboard implementations.

abstract clear()

abstract copy(data, encoding=None)

abstract paste(encoding=None, text=None, errors=None)

Return type

Union[str, bytes]

exception pyclip.base.ClipboardException

exception pyclip.base.ClipboardSetupException

pyclip cli module

pyclip.cli.main()

pyclip macos_clip module

Provides clipboard for MacOS

class pyclip.macos_clip.MacOSClip(_backend=None)

Provides Clipboard functionality for MacOS.

Defers to one of two backends: _PasteboardBackend (the default) or _PBCopyPBPasteBackend.

clear()

Clear the clipboard contents

Returns

copy(data, encoding=None)

Parameters

• data (Union[str, bytes]) – data to copy to the clipboard

• encoding (Optional[str]) – this parameter is ignored on this backend

Returns

paste(encoding=None, text=None, errors=None)

Retrieve contents of the clipboard

Parameters

• encoding (Optional[str]) – same meaning as in bytes.encode. Implies text=True

• text (Optional[bool]) – if True, bytes object will be en

• errors (Optional[str]) – same meaning as in bytes.encode. Implies text=True.

Returns

clipboard contents. Return value is bytes by default

or str if any of encoding, text, or errors is provided.

pyclip util module

pyclip.util.detect_clipboard()

Determine what implementation to use based on sys.platform

Return type

ClipboardBase

pyclip win_clip module

Provides clipboard functionality for Windows via the pywin32 package

exception pyclip.win_clip.ClipboardNotTextFormatException

exception pyclip.win_clip.UnparsableClipboardFormatException

class pyclip.win_clip.WindowsClipboard

clear()

Clear the clipboard contents

Return type

None

Returns

copy(data, encoding=None)

Copy given string into system clipboard.

paste(encoding=None, text=None, errors=None)

Returns clipboard contents

Parameters

• encoding (Optional[str]) – same meaning as in bytes.encode. Implies text=True

• text (Optional[bool]) – if True, bytes object will be en

• errors (Optional[str]) – same meaning as in bytes.encode. Implies text=True.

Return type

Union[str, bytes]

Returns

clipboard contents. Return value is bytes by default or str if any of encoding, text, or errors is provided.

pyclip xclip_clip module

Provides the clipboard functionality for Linux via xclip

class pyclip.xclip_clip.XclipClipboard

clear()

Clear the clipboard contents

Returns

copy(data, encoding=None)

Copy data into the clipboard

Parameters

• data (Union[str, bytes]) – the data to be copied to the clipboard. Can be str or bytes.

• encoding (Optional[str]) – same meaning as in subprocess.Popen.

Return type

None

Returns

None

paste(encoding=None, text=None, errors=None)

Retrieve data from the clipboard

Parameters

• encoding (Optional[str]) – same meaning as in subprocess.run

• text (Optional[bool]) – same meaning as in subprocess.run

• errors (Optional[str]) – same meaning as in subprocess.run

Returns

the clipboard contents. return type is binary by default. If any of encoding, errors, or text are specified, the result type is str

Other modules:

__main__.py

Simple entrypoint for calling pyclip via python -m pyclip. Uses pyclip.cli.main as entrypoint.

Indices and tables

• Index

• Module Index

• Search Page