日々のコピペ作業をPythonで自動化できれば、資料作成やデータ整理が一気に効率化します。
pyperclipは、OSのクリップボードにシンプルなAPIでアクセスできる軽量ライブラリです。
本記事では、インストールから基本操作、実用レシピ、トラブル対応まで初心者向けに丁寧に解説します。
pyperclipとは?
pyperclipの特徴とできること
pyperclipは、Pythonからクリップボードにテキストを簡単かつクロスプラットフォームに読み書きできるライブラリです。
関数はpyperclip.copy(text)
とpyperclip.paste()
の2つが中心で、Python初心者でもすぐに使い始められます。
実務では次のような場面で役立ちます。
例えば、Webスクレイピングで抽出したテキストを整形してすぐに貼り付けたいとき、あるいはExcelからコピーしたデータを自動でスペース整形して再コピーするなどです。
コードの複雑さを極力抑えられるため、「とにかくテキストのコピペを自動化したい」というニーズに最適です。
pyperclipは依存が少なく、特にWindowsとmacOSではインストール直後からそのまま動作しやすいのが利点です。
対応OS(Windows/Mac/Linux)と動作要件
基本的に主要OSに対応していますが、Linuxのみ追加コマンドが必要になる場合があります。
OS | 追加要件 | 備考 |
---|---|---|
Windows 10以降 | 特になし | そのまま動作します。PowerShell/コマンドプロンプトで利用可能です。 |
macOS | 特になし | pbcopy/pbpasteを内部で使用します。 |
Linux(Ubuntu/Fedora/Archなど) | xclip または xsel のインストールが必要 | デスクトップ環境により追加設定が必要なことがあります。 |
特にLinuxでは「pyperclipがコピー/ペースト手段を見つけられない」例外が出ることがあります。
その場合は後述の対処を参照してください。
インストール手順
Pythonが入っていれば、まずはpipでインストールします。
初心者の方はpython -m pip
の形で実行すると、Python本体とpipの対応がズレにくく安全です。
# 共通(推奨)
python -m pip install --upgrade pip
python -m pip install pyperclip
# Windowsで複数バージョンのPythonが入っている場合
py -m pip install pyperclip
# macOSでHomebrewのPythonを使っている場合の例
python3 -m pip install pyperclip
Linuxで動作しない場合は、以下のどちらかを追加インストールします。
# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y xclip # または xsel
# Fedora
sudo dnf install -y xclip # または xsel
# Arch Linux
sudo pacman -S xclip # または xsel
インストール後の確認は次のとおりです。
# 確認用: バージョンと簡単な動作チェック
import pyperclip
print("pyperclip version:", getattr(pyperclip, "__version__", "unknown"))
pyperclip.copy("OK")
print("copied:", pyperclip.paste())
pyperclip version: 1.8.2
copied: OK
もしエラーが出た場合は、後述の「トラブル対応」を参照してください。
基本の使い方
文字列をコピーする
もっともシンプルな例です。
テキストをコピーし、確認のために貼り付け内容を取得して表示します。
# 基本: 文字列をクリップボードにコピー
import pyperclip
message = "Hello, Clipboard!"
pyperclip.copy(message) # クリップボードにコピー
print("コピーしました。次に貼り付け(Ctrl+Vなど)で確認できます。")
print("確認用(取得):", pyperclip.paste())
コピーしました。次に貼り付け(Ctrl+Vなど)で確認できます。
確認用(取得): Hello, Clipboard!
クリップボードから取得する
既にクリップボードに何かテキストが入っている前提で、取得してPythonで使います。
# 基本: クリップボードからテキストを取得
import pyperclip
text = pyperclip.paste() # クリップボードの内容を取得
# 空の場合は空文字("")が返ります
if text:
print("取得したテキスト:", text)
else:
print("クリップボードは空(またはテキスト以外)です。")
取得したテキスト: 例) メモしておきたい文章
pyperclipは常に文字列(Unicode)を返します。
クリップボードが空でもNone
ではなく空文字""
が返る点に注意してください。
日本語・改行を含むテキストの扱い
日本語や絵文字、複数行の改行を含むテキストも問題なく扱えます。
表示の文字化けはコンソール側の文字コード設定が原因のことが多く、テキスト自体は正しくコピーされています。
# 日本語・改行・絵文字のコピーと確認
import pyperclip
multi = "こんにちは、世界🌏\n複数行のテキストを\nそのままコピーします。"
pyperclip.copy(multi)
pasted = pyperclip.paste()
print("取得文字数:", len(pasted))
print("--- 内容 ---")
print(pasted)
取得文字数: 31
--- 内容 ---
こんにちは、世界🌏
複数行のテキストを
そのままコピーします。
Windowsの旧コンソールで表示が崩れる場合はUTF-8に切り替える(例: chcp 65001)と改善します。
詳しくは後述の「文字化け対策」を参照してください。
すぐ使えるレシピ
余分な空白を除去してコピー
フォームからコピーしたテキストには、先頭末尾の空白やタブが混入しがちです。
ここでは連続スペースやタブを1つの半角スペースに圧縮し、先頭末尾の空白を除去してから再コピーします。
# 余分な空白(スペース/タブ)を整理して再コピー
import re
import pyperclip
def normalize_spaces(s: str) -> str:
# 1) 先頭末尾の空白を削除
s = s.strip()
# 2) 連続するスペース/タブを単一スペースに
s = re.sub(r"[ \t]+", " ", s)
return s
original = " Python\t 入門 メモ "
cleaned = normalize_spaces(original)
pyperclip.copy(cleaned) # 整理した文字列をコピー
print("元:", repr(original))
print("整形後:", repr(cleaned))
print("クリップボード:", repr(pyperclip.paste()))
元: ' Python\t 入門 メモ '
整形後: 'Python 入門 メモ'
クリップボード: 'Python 入門 メモ'
データの前処理として非常に有用で、貼り付け時の見た目が安定します。
複数行テキストを整形してコピー
メールやWebからのコピーは行頭の空白や空行が混ざることがあります。
ここでは各行の前後空白を削除し、空行を除去して読みやすく整形します。
# 複数行テキストを整形: 前後空白を除去し、空行を削除
import textwrap
import pyperclip
original = textwrap.dedent("""\
タイトル: 週次レポート
- 進捗 A
- 詳細 A1
- 進捗 B
終了
""")
def tidy_multiline(s: str) -> str:
lines = s.splitlines()
# 各行の前後空白を削除し、空行は落とす
lines = [line.strip() for line in lines]
lines = [line for line in lines if line] # 空行除去
return "\n".join(lines)
result = tidy_multiline(original)
pyperclip.copy(result)
print("--- 元 ---")
print(original)
print("--- 整形後 ---")
print(result)
--- 元 ---
タイトル: 週次レポート
- 進捗 A
- 詳細 A1
- 進捗 B
終了
--- 整形後 ---
タイトル: 週次レポート
- 進捗 A
- 詳細 A1
- 進捗 B
終了
読みやすさが大きく向上し、Slackやメールにそのまま貼り付けやすくなります。
定型文をすぐコピー
よく使う定型文をスクリプト化しておくと、キーボード操作だけでコピーできて便利です。
日付や名前などの差し込みにも対応させられます。
# 定型文ランチャー: 数字で選んでクリップボードにコピー
import datetime as dt
import pyperclip
today = dt.date.today().strftime("%Y-%m-%d")
templates = {
"1": f"お世話になっております。\n株式会社サンプルの山田です。\n{today}の件でご連絡しました。",
"2": f"ご確認ありがとうございます。\n取り急ぎ、受領のご連絡まで。\n{today}",
"3": f"会議の議事要旨です。\n- 日付: {today}\n- 参加者: 佐藤/鈴木/田中",
}
print("番号を選んでください (1:挨拶メール, 2:受領連絡, 3:議事要旨): ", end="")
choice = input().strip()
msg = templates.get(choice)
if msg:
pyperclip.copy(msg)
print("コピーしました。Ctrl+Vで貼り付けできます。")
else:
print("不正な番号です。")
番号を選んでください (1:挨拶メール, 2:受領連絡, 3:議事要旨): 1
コピーしました。Ctrl+Vで貼り付けできます。
小さなユーティリティとして保存し、OSのショートカットやランチャーから呼び出すとさらに便利です。
トラブル対応
Linuxでxclip/xselが必要な場合
Linuxではpyperclipが内部で利用するコピー/ペーストコマンド(xclipまたはxsel)が必須です。
未インストールだと以下のような例外が発生します。
# エラーメッセージ確認用
import pyperclip
try:
pyperclip.copy("test") # ここで例外になる場合があります
print("コピー成功")
except pyperclip.PyperclipException as e:
print("PyperclipException:", e)
PyperclipException: Pyperclip could not find a copy/paste mechanism for your system.
この場合は、次のどちらかをインストールしてください。
# Debian/Ubuntu
sudo apt-get install -y xclip # または xsel
# Fedora
sudo dnf install -y xclip # または xsel
# Arch Linux
sudo pacman -S xclip # または xsel
Wayland環境でうまく動かないときは、XWaylandを有効にしてxclipを使うか、デスクトップ環境のクリップボード設定も確認してください。
仮想環境やPATHの確認
「インストールしたのにimportできない」「スクリプトでは使えるが対話シェルでは使えない」といった問題は、pipとPythonの組み合わせ(パス)がズレていることが多いです。
- まずは
python -m pip install pyperclip
のように、使いたいPythonに紐づくpipでインストールします。Windowsではpy -m pip
が安全です。 - 仮想環境(venv)を使う場合は、アクティブ化してからインストールします。
# 仮想環境の作成と有効化(例)
python -m venv .venv
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# macOS/Linux (bash/zsh)
source .venv/bin/activate
# 有効化後にインストール
python -m pip install pyperclip
実際にどのPython/pyperclipが使われているかは、以下で確認できます。
# 実際に参照しているPythonとpyperclipの場所を確認
import sys, pyperclip
print("Python実行ファイル:", sys.executable)
print("pyperclipの場所:", getattr(pyperclip, "__file__", "不明"))
Python実行ファイル: C:\Projects\demo\.venv\Scripts\python.exe
pyperclipの場所: C:\Projects\demo\.venv\Lib\site-packages\pyperclip\__init__.py
もしパスが意図した環境と異なる場合は、その環境を有効化し直すか、フルパスで実行してください。
文字化け対策とエラーの見分け方
「文字化け」はテキスト自体が壊れているのではなく、表示側(コンソール)の文字コード設定が原因のことが多いです。
クリップボードの中身は正しいのに、print表示が乱れるケースに注意してください。
症状 | よくある原因 | 対処 |
---|---|---|
日本語や絵文字がprintで化ける(Windows) | 旧コンソールの文字コードがUTF-8でない | PowerShell使用、またはchcp 65001 、PYTHONUTF8=1 |
Linuxでコピーが失敗する | xclip/xselが未インストール | sudo apt install xclip などで導入 |
pasteが空文字になる | クリップボードが空、または非テキスト | 先にcopy で明示的に文字列を入れる |
例外PyperclipException | 仕組みが見つからない/権限不足 | 依存ツール導入、環境の権限確認 |
デバッグ時はrepr()
で内部の実体を確認すると状況を切り分けやすくなります。
# 文字実体の確認と例外ハンドリングの例
import os
import pyperclip
try:
text = "テスト🌟"
pyperclip.copy(text)
got = pyperclip.paste()
print("reprで確認:", repr(got)) # エスケープ表示で実体を確認
except pyperclip.PyperclipException as e:
print("クリップボード関連の例外:", e)
# Linuxなら xclip/xsel の導入を案内するなど
reprで確認: 'テスト🌟'
reprで正しく見えていれば、コピー自体は成功しており、表示側設定の問題である可能性が高いです。
まとめ
本記事では、Python×pyperclipでクリップボードのテキストを簡単に操作する方法を、導入から基本操作、実用的な整形レシピ、トラブル対応まで一通り解説しました。
特にWindowsやmacOSでは導入が容易で、コピー/ペーストの自動化をすぐに実践できます。
Linuxではxclip/xselの導入を忘れずに行い、仮想環境やPATHのズレを避けるためにpython -m pip
でのインストールを心がけると安定します。
日々の定型コピペやテキスト整形をスクリプト化することで、細かな作業時間を大きく短縮できます。
まずは小さなユーティリティから始め、快適なテキスト自動化環境を作っていきましょう。