📸 PyAutoGUI スクリーンショット

📖 はじめに

PyAutoGUIでは、現在の画面をスクリーンショットとして取得できます。

取得したスクリーンショットは、次のような用途に利用できます。

操作結果の記録
エラー発生時の画面保存
定期的な画面取得
画像認識に使用する検索画像の作成
自動処理が正常に完了したことの確認

この記事では、画面全体の保存から範囲指定、日時付きファイル名、連続撮影まで、スクリーンショット機能の基本的な使い方を説明します。

📦 PyAutoGUIの読み込み

最初にPyAutoGUIをインポートします。

import pyautogui

スクリーンショットをファイルとして保存するだけであれば、基本的にはこれだけで利用できます。

🖥️ 画面全体を取得する

画面全体のスクリーンショットはscreenshot()で取得します。

import pyautogui

image = pyautogui.screenshot()

取得した画像はimage変数に格納されます。

この時点では、画像はまだファイルとして保存されていません。

screenshot()の戻り値はPillowのImageオブジェクトです。取得後に保存したり、切り抜いたり、画像処理へ渡したりできます。

💾 スクリーンショットを保存する

screenshot()へファイル名を渡すと、取得と保存を同時に行えます。

import pyautogui

pyautogui.screenshot("screenshot.png")

Pythonファイルを実行した場所に、次のファイルが作成されます。

screenshot.png

画像オブジェクトを取得しながら保存することもできます。

import pyautogui

image = pyautogui.screenshot("screenshot.png")

print(image.size)

📁 保存先を指定する

フォルダを含むパスを指定すると、任意の場所へ保存できます。

import pyautogui

pyautogui.screenshot(
    "screenshots/screenshot.png"
)

ただし、保存先のフォルダが存在しない場合はエラーになります。

PyAutoGUIは、指定した保存先フォルダを自動では作成しません。先にフォルダを作成しておく必要があります。

📂 保存先フォルダを自動作成する

pathlibを使用すると、保存先フォルダがない場合に自動作成できます。

from pathlib import Path

import pyautogui


output_dir = Path("screenshots")
output_dir.mkdir(
    parents=True,
    exist_ok=True
)

output_path = output_dir / "screenshot.png"

pyautogui.screenshot(
    str(output_path)
)

mkdir()の引数には次の意味があります。

引数	意味
`parents=True`	上位フォルダも必要に応じて作成する
`exist_ok=True`	フォルダがすでに存在してもエラーにしない

スクリーンショットを自動保存するスクリプトでは、pathlibを使って保存先フォルダを準備しておくと安全です。

✂️ 画面の一部分だけを取得する

画面全体ではなく、指定した範囲だけを撮影できます。

import pyautogui

pyautogui.screenshot(
    "partial.png",
    region=(100, 200, 800, 600)
)

regionには、次の順番で値を指定します。

(left, top, width, height)

この例では、次の範囲を取得します。

項目	値
左端のX座標	100
上端のY座標	200
幅	800
高さ	600

右端と下端の座標を指定するのではなく、左上の座標と画像の大きさを指定します。

画面左上が座標(0, 0)です。右へ進むほどX座標が増え、下へ進むほどY座標が増えます。

📍 撮影範囲の座標を調べる

現在のマウスカーソルの座標はposition()で確認できます。

import pyautogui

x, y = pyautogui.position()

print(x, y)

撮影したい範囲の左上と右下へマウスを移動し、それぞれの座標を確認すると範囲を決められます。

右下の座標が分かっている場合は、幅と高さを次のように求めます。

left = 100
top = 200

right = 900
bottom = 800

width = right - left
height = bottom - top

print(width, height)

結果は次のようになります。

800 600

この値をregionへ指定します。

region = (
    left,
    top,
    width,
    height
)

pyautogui.screenshot(
    "partial.png",
    region=region
)

🔎 マウス座標を連続表示する

撮影範囲を調べる場合は、マウス座標を連続表示すると便利です。

import time

import pyautogui


try:
    while True:
        x, y = pyautogui.position()

        print(
            f"\rX={x:4d}, Y={y:4d}",
            end=""
        )

        time.sleep(0.1)

except KeyboardInterrupt:
    print("\n終了しました。")

実行中にマウスを動かすと、現在位置が更新されます。

終了するときは、ターミナル上でCtrl+Cを押します。

⏳ 数秒後に撮影する

スクリプトを実行したあと、撮影したい画面へ切り替える時間が必要な場合があります。

time.sleep()を使用すると、撮影前に待機できます。

import time

import pyautogui


time.sleep(5)

pyautogui.screenshot(
    "screenshot.png"
)

この例では、スクリプトを実行してから5秒後に撮影します。

🔢 カウントダウンしてから撮影する

撮影までの残り時間を表示すると、画面を準備しやすくなります。

import time

import pyautogui


for remaining in range(5, 0, -1):
    print(
        f"{remaining}秒後に撮影します。"
    )

    time.sleep(1)

pyautogui.screenshot(
    "screenshot.png"
)

print("撮影しました。")

手動で画面を準備して撮影する場合は、数秒のカウントダウンを入れると操作しやすくなります。

🕒 日時をファイル名に入れる

毎回同じファイル名で保存すると、以前の画像が上書きされます。

撮影日時をファイル名に含めると、画像を残しておけます。

from datetime import datetime

import pyautogui


timestamp = datetime.now().strftime(
    "%Y%m%d_%H%M%S"
)

filename = (
    f"screenshot_{timestamp}.png"
)

pyautogui.screenshot(filename)

print(filename)

例えば、次のようなファイル名で保存されます。

screenshot_20260806_101530.png

使用している書式の意味は次のとおりです。

書式	意味
`%Y`	西暦4桁
`%m`	月
`%d`	日
`%H`	時
`%M`	分
`%S`	秒

🗂️ 日時付きで指定フォルダへ保存する

実用的には、保存先フォルダの作成と日時付きファイル名を組み合わせます。

from datetime import datetime
from pathlib import Path

import pyautogui


output_dir = Path("screenshots")
output_dir.mkdir(
    parents=True,
    exist_ok=True
)

timestamp = datetime.now().strftime(
    "%Y%m%d_%H%M%S"
)

output_path = output_dir / (
    f"screenshot_{timestamp}.png"
)

pyautogui.screenshot(
    str(output_path)
)

print(
    f"保存しました: {output_path}"
)

自動保存では、保存先フォルダの作成と日時付きファイル名を組み合わせると、上書きを防ぎながら画像を整理できます。

🖼️ 取得した画像をあとから保存する

screenshot()で取得した画像は、save()を使ってあとから保存できます。

import pyautogui


image = pyautogui.screenshot()

image.save(
    "screenshot.png"
)

この書き方は、保存前に画像を加工したい場合に便利です。

✂️ 取得後に画像を切り抜く

取得した画像はPillowのImageオブジェクトなので、crop()で切り抜けます。

import pyautogui


image = pyautogui.screenshot()

cropped = image.crop(
    (100, 200, 900, 800)
)

cropped.save(
    "cropped.png"
)

crop()では、次の順番で座標を指定します。

(left, top, right, bottom)

これはscreenshot()のregionとは指定方法が異なります。

機能	指定方法
`screenshot(region=...)`	左、上、幅、高さ
`image.crop(...)`	左、上、右、下

regionとcrop()では、範囲の指定方法が異なります。幅・高さと右端・下端を取り違えないよう注意してください。

📏 画像のサイズを確認する

取得した画像の幅と高さはsizeで確認できます。

import pyautogui


image = pyautogui.screenshot()

width, height = image.size

print(
    f"幅: {width}px"
)

print(
    f"高さ: {height}px"
)

画面全体を取得した場合は、通常、使用している画面の解像度に対応した値が表示されます。

🎨 画像の特定位置の色を取得する

画像内の指定座標の色はgetpixel()で取得できます。

import pyautogui


image = pyautogui.screenshot()

color = image.getpixel(
    (500, 300)
)

print(color)

RGB画像の場合、次のような値が得られます。

(255, 255, 255)

この例では、赤・緑・青がすべて255なので白色です。

この機能を利用すると、画面上の特定位置の色が変わったかどうかを判定できます。

🌈 画面上の色を直接取得する

PyAutoGUIのpixel()を使用すると、スクリーンショット全体を変数へ保存せずに、指定位置の色を取得できます。

import pyautogui


color = pyautogui.pixel(
    500,
    300
)

print(color)

特定位置が期待する色かどうかはpixelMatchesColor()で確認できます。

import pyautogui


matched = pyautogui.pixelMatchesColor(
    500,
    300,
    (255, 255, 255)
)

print(matched)

一致した場合はTrue、一致しない場合はFalseになります。

色に多少の違いを許容する場合はtoleranceを指定します。

matched = pyautogui.pixelMatchesColor(
    500,
    300,
    (255, 255, 255),
    tolerance=10
)

ボタンの有効・無効や処理完了を色で判定できる画面では、画像認識よりも特定座標の色を確認する方が簡単な場合があります。

🔁 一定間隔で連続撮影する

一定時間ごとにスクリーンショットを保存できます。

import time
from datetime import datetime
from pathlib import Path

import pyautogui


output_dir = Path("screenshots")
output_dir.mkdir(
    parents=True,
    exist_ok=True
)

interval = 10

try:
    while True:
        timestamp = datetime.now().strftime(
            "%Y%m%d_%H%M%S"
        )

        output_path = output_dir / (
            f"screenshot_{timestamp}.png"
        )

        pyautogui.screenshot(
            str(output_path)
        )

        print(
            f"保存しました: {output_path}"
        )

        time.sleep(interval)

except KeyboardInterrupt:
    print("撮影を終了しました。")

この例では、10秒ごとに画面全体を保存します。

ターミナルでCtrl+Cを押すと終了します。

短い間隔で連続撮影すると、大量の画像が作成され、ストレージ容量を消費します。撮影間隔と保存期間を事前に決めてください。

🔢 撮影回数を指定する

無期限ではなく、指定回数だけ撮影することもできます。

import time
from datetime import datetime
from pathlib import Path

import pyautogui


output_dir = Path("screenshots")
output_dir.mkdir(
    parents=True,
    exist_ok=True
)

capture_count = 5
interval = 10

for number in range(
    1,
    capture_count + 1
):
    timestamp = datetime.now().strftime(
        "%Y%m%d_%H%M%S"
    )

    output_path = output_dir / (
        f"screenshot_{number:03d}_"
        f"{timestamp}.png"
    )

    pyautogui.screenshot(
        str(output_path)
    )

    print(
        f"{number}/{capture_count}: "
        f"{output_path}"
    )

    if number < capture_count:
        time.sleep(interval)

次のようなファイル名で保存されます。

screenshot_001_20260806_101500.png
screenshot_002_20260806_101510.png
screenshot_003_20260806_101520.png

🪟 特定のウィンドウ範囲を撮影する

PyAutoGUIのscreenshot()は、ウィンドウ名を直接指定して撮影する機能ではありません。

Windowsでは、PyGetWindowを利用してウィンドウの位置と大きさを取得し、その範囲をregionへ渡す方法があります。

最初にPyGetWindowをインストールします。

pip install pygetwindow

次の例では、タイトルに「メモ帳」を含むウィンドウを撮影します。

import pyautogui
import pygetwindow


windows = pygetwindow.getWindowsWithTitle(
    "メモ帳"
)

if not windows:
    print(
        "対象のウィンドウが"
        "見つかりませんでした。"
    )

else:
    window = windows[0]

    region = (
        window.left,
        window.top,
        window.width,
        window.height
    )

    pyautogui.screenshot(
        "notepad.png",
        region=region
    )

    print("撮影しました。")

ウィンドウタイトルは、開いているファイル名やアプリケーションの状態によって変わることがあります。

🪟 ウィンドウを前面にしてから撮影する

対象ウィンドウがほかのウィンドウに隠れている場合は、そのままでは隠れた状態が撮影されます。

撮影前に対象を前面へ移動します。

import time

import pyautogui
import pygetwindow


windows = pygetwindow.getWindowsWithTitle(
    "メモ帳"
)

if not windows:
    print(
        "対象のウィンドウが"
        "見つかりませんでした。"
    )

else:
    window = windows[0]

    if window.isMinimized:
        window.restore()

    window.activate()

    time.sleep(1)

    region = (
        window.left,
        window.top,
        window.width,
        window.height
    )

    pyautogui.screenshot(
        "notepad.png",
        region=region
    )

PyAutoGUIは、画面上に実際に表示されている内容を撮影します。対象ウィンドウが最小化されていたり、別のウィンドウに隠れていたりすると、期待した画像になりません。

🧰 スクリーンショット保存を関数にする

繰り返し使用する場合は、日時付きで保存する処理を関数にすると便利です。

from datetime import datetime
from pathlib import Path

import pyautogui


def save_screenshot(
    output_dir="screenshots",
    prefix="screenshot",
    region=None
):
    directory = Path(output_dir)

    directory.mkdir(
        parents=True,
        exist_ok=True
    )

    timestamp = datetime.now().strftime(
        "%Y%m%d_%H%M%S_%f"
    )

    output_path = directory / (
        f"{prefix}_{timestamp}.png"
    )

    pyautogui.screenshot(
        str(output_path),
        region=region
    )

    return output_path

画面全体を撮影します。

saved_path = save_screenshot()

print(
    f"保存しました: {saved_path}"
)

指定範囲を撮影します。

saved_path = save_screenshot(
    prefix="browser",
    region=(100, 100, 1200, 800)
)

ファイル名にマイクロ秒まで含めているため、同じ秒に複数回撮影しても上書きされにくくなっています。

🚨 エラー発生時の画面を保存する

自動操作中にエラーが発生した場合、そのときの画面を保存すると原因を調べやすくなります。

from datetime import datetime
from pathlib import Path

import pyautogui


output_dir = Path("error_screenshots")

output_dir.mkdir(
    parents=True,
    exist_ok=True
)

try:
    center = (
        pyautogui.locateCenterOnScreen(
            "images/save_button.png",
            confidence=0.9
        )
    )

    pyautogui.click(center)

except Exception as error:
    timestamp = datetime.now().strftime(
        "%Y%m%d_%H%M%S"
    )

    output_path = output_dir / (
        f"error_{timestamp}.png"
    )

    pyautogui.screenshot(
        str(output_path)
    )

    print(
        f"エラー画面を保存しました: "
        f"{output_path}"
    )

    raise

最後のraiseは、スクリーンショットを保存したあとで、発生したエラーを改めて送出します。

GUI自動化では、エラー発生時のスクリーンショットを保存しておくと、「どの画面で停止したか」を後から確認できます。

🧾 操作の前後を撮影する

重要な操作では、実行前と実行後の両方を記録すると確認しやすくなります。

import time
from datetime import datetime
from pathlib import Path

import pyautogui


output_dir = Path("evidence")
output_dir.mkdir(
    parents=True,
    exist_ok=True
)

timestamp = datetime.now().strftime(
    "%Y%m%d_%H%M%S"
)

before_path = output_dir / (
    f"{timestamp}_before.png"
)

after_path = output_dir / (
    f"{timestamp}_after.png"
)

pyautogui.screenshot(
    str(before_path)
)

pyautogui.click(
    800,
    500
)

time.sleep(1)

pyautogui.screenshot(
    str(after_path)
)

操作前後の画像を同じ日時で関連付けて保存できます。

⚠️ スクリーンショット利用時の注意

🔒 個人情報や機密情報

画面全体を撮影すると、意図していない情報も画像に含まれることがあります。

例えば、次のような情報です。

氏名
メールアドレス
顧客情報
パスワード
アクセストークン
通知内容
社内システムの情報

スクリーンショットには、個人情報や認証情報、業務上の機密情報が含まれる可能性があります。 保存先、保存期間、閲覧権限、外部共有の可否を事前に確認してください。

💽 保存容量

画面全体の画像は、撮影回数によっては大きな容量になります。

特に次の条件では、保存容量が急速に増えます。

高解像度ディスプレイ
複数画面
短い撮影間隔
長期間の保存
PNG形式での大量保存

連続撮影する場合は、古い画像を削除する仕組みも検討します。

🖱️ マウスカーソル

環境や撮影方法によっては、マウスカーソルが画像に含まれないことがあります。

クリック位置を記録したい場合は、座標をログとして別途保存する方法があります。

import pyautogui


x, y = pyautogui.position()

print(
    f"撮影時のマウス位置: "
    f"({x}, {y})"
)

pyautogui.screenshot(
    "screenshot.png"
)

🎞️ 動画やアニメーション

動画、アニメーション、読み込み表示などを撮影すると、撮影タイミングによって内容が変化します。

特定の状態を撮影したい場合は、

画像が表示されるまで待つ
特定位置の色が変わるまで待つ
処理完了を示すボタンを画像認識する

といった待機処理を組み合わせます。

💡 実践例：指定ウィンドウを定期撮影する

次の例では、タイトルに「Google Chrome」を含むウィンドウを10秒間隔で5回撮影します。

import time
from datetime import datetime
from pathlib import Path

import pyautogui
import pygetwindow


output_dir = Path("screenshots")
output_dir.mkdir(
    parents=True,
    exist_ok=True
)

windows = pygetwindow.getWindowsWithTitle(
    "Google Chrome"
)

if not windows:
    raise RuntimeError(
        "対象のウィンドウが"
        "見つかりませんでした。"
    )

window = windows[0]

if window.isMinimized:
    window.restore()

window.activate()

time.sleep(1)

for number in range(1, 6):
    timestamp = datetime.now().strftime(
        "%Y%m%d_%H%M%S"
    )

    output_path = output_dir / (
        f"chrome_{number:03d}_"
        f"{timestamp}.png"
    )

    region = (
        window.left,
        window.top,
        window.width,
        window.height
    )

    pyautogui.screenshot(
        str(output_path),
        region=region
    )

    print(
        f"保存しました: {output_path}"
    )

    if number < 5:
        time.sleep(10)

このコードには、スクリーンショット自動化でよく使う処理が含まれています。

保存先フォルダの作成
対象ウィンドウの検索
最小化状態からの復元
ウィンドウの前面表示
ウィンドウ範囲の取得
日時付きファイル名
指定間隔での連続撮影
撮影回数の制限

📝 まとめ

PyAutoGUIでは、screenshot()を使用して現在の画面を取得できます。

代表的な操作は次のとおりです。

screenshot()：画面を取得する
screenshot("画像名.png")：取得と保存を同時に行う
region：撮影範囲を指定する
save()：取得した画像をあとから保存する
crop()：取得後の画像を切り抜く
pixel()：指定座標の色を取得する
pixelMatchesColor()：指定座標の色を判定する

実際の自動化では、次の処理を組み合わせると便利です。

撮影前にカウントダウンする
日時をファイル名に含める
保存先フォルダを自動作成する
一定間隔で連続撮影する
特定のウィンドウ範囲だけを撮影する
エラー発生時の画面を保存する
操作の前後を記録する

スクリーンショットは単なる画面保存だけでなく、自動操作の確認、障害調査、画像認識用データの作成など、GUI自動化を安定させるための重要な機能です。

FastAPIとGradioの使い分け

FastAPIとGradioの連携サンプル

Gradio Blocks入門：Blocksだからできる複雑UIを体験しよう

Gradio.interface と Gradio.Blocks

Gradio（グラディオ）について

Gradioで作る！英作文の自動添削アプリ

Gradioで単語カウンターアプリを作る

gradioの部品まとめ

Tkとの比較～なぜスタンドアローンでもよいのにhttp使うのか？

matplotlibで山手線上の駅を移動する点をアニメーションで描写する

matplotlibの概要

VOICEVOX Dockerイメージを使用して音声合成APIサーバーを構築して遊ぶ手順書

pytestをVS Codeで快適に運用する方法

pytestのデコレータ実践ガイド（parametrize / fixture / mark / skip / xfail）

🖱️ PyAutoGUI 概要

💿 PyAutoGUI インストール方法

🖱️ PyAutoGUI マウス操作

⌨️ PyAutoGUI キーボード操作

🔍 PyAutoGUI 画像認識

📸 PyAutoGUI スクリーンショット

🪟 PyGetWindowによるウィンドウ操作

📸 PyAutoGUI スクリーンショット

📖 はじめに

📦 PyAutoGUIの読み込み

🖥️ 画面全体を取得する

💾 スクリーンショットを保存する

📁 保存先を指定する

📂 保存先フォルダを自動作成する

✂️ 画面の一部分だけを取得する

📍 撮影範囲の座標を調べる

🔎 マウス座標を連続表示する

⏳ 数秒後に撮影する

🔢 カウントダウンしてから撮影する

🕒 日時をファイル名に入れる

🗂️ 日時付きで指定フォルダへ保存する

🖼️ 取得した画像をあとから保存する

✂️ 取得後に画像を切り抜く

📏 画像のサイズを確認する

🎨 画像の特定位置の色を取得する

🌈 画面上の色を直接取得する

🔁 一定間隔で連続撮影する

🔢 撮影回数を指定する

🪟 特定のウィンドウ範囲を撮影する

🪟 ウィンドウを前面にしてから撮影する

🧰 スクリーンショット保存を関数にする

🚨 エラー発生時の画面を保存する

🧾 操作の前後を撮影する

⚠️ スクリーンショット利用時の注意

🔒 個人情報や機密情報

💽 保存容量

🖱️ マウスカーソル

🎞️ 動画やアニメーション

💡 実践例：指定ウィンドウを定期撮影する

📝 まとめ