【Python】PyAutoGUIで画面をスクロールする：縦スクロール・横スクロール

2026年1月13日

概要

PyAutoGUIを使用して、Webページや長いドキュメントをスクロール操作する方法を解説します。基本的な縦方向のスクロール（scroll）に加え、スプレッドシートなどで役立つ横方向のスクロール（hscroll）についても触れます。数値の正負による方向の違いを理解することがポイントです。

仕様（入出力）

入力:
- スクロール量（整数: clicks）
- マウスカーソル位置（オプション: x, y）
出力:
- アクティブウィンドウまたはマウス下のウィンドウのスクロール動作
前提:
- pyautogui ライブラリのインストールが必要です。
- スクロール操作は「現在マウスカーソルがある位置のウィンドウ」に対して行われるのが一般的です。

基本の使い方

縦方向に画面をスクロールさせる基本的なコードです。正の値で「上」へ、負の値で「下」へスクロールします。

import pyautogui
import time

# 準備時間
time.sleep(2)

# 上にスクロール（Webページの上部へ戻る動き）
pyautogui.scroll(500)

# 下にスクロール（Webページを読み進める動き）
pyautogui.scroll(-500)

コード全文

ブラウザやエディタ上で、上下のスクロールと水平スクロールを連続して行うデモコードです。 ※横スクロールは対応しているアプリケーション上でのみ動作します。

import pyautogui
import time

def scroll_demonstration():
    """
    縦スクロールと横スクロールの動作を確認するデモ関数です。
    実行後すぐにスクロール可能なウィンドウ（ブラウザ等）をアクティブにしてください。
    """
    pyautogui.FAILSAFE = True
    
    print("3秒後にスクロール操作を開始します...")
    print("ブラウザやエディタにマウスカーソルを置いてください。")
    time.sleep(3)

    try:
        # 1. 縦スクロール (Vertical Scroll)
        # 引数の数値は「クリック数」に相当し、感度はOS設定に依存します
        
        print("下にスクロール中...")
        for _ in range(3):
            pyautogui.scroll(-300) # 負の値 = 下方向
            time.sleep(0.5)

        print("上にスクロール中...")
        pyautogui.scroll(900)      # 正の値 = 上方向
        time.sleep(1)

        # 2. 横スクロール (Horizontal Scroll)
        # ※OSやアプリによっては動作しない場合があります（主にLinux/macOS向け機能）
        print("右にスクロール試行中...")
        pyautogui.hscroll(100)     # 正の値 = 右方向
        time.sleep(0.5)
        
        print("左にスクロール試行中...")
        pyautogui.hscroll(-100)    # 負の値 = 左方向

        print("操作完了")

    except KeyboardInterrupt:
        print("中断されました。")

if __name__ == "__main__":
    scroll_demonstration()

カスタムポイント

パラメータの意味

scroll(clicks, x=None, y=None)

clicks (int):
- スクロール量を整数で指定します。
- 正の値 (+): 上へスクロール（ホイールを奥へ回す）
- 負の値 (-): 下へスクロール（ホイールを手前へ回す）
x, y (int):
- 指定すると、まずその座標へマウスを移動してからスクロールを実行します。
- スクロールイベントは「マウスカーソルの下にあるウィンドウ」に送られるため、この引数が役立ちます。

横スクロール (hscroll)

pyautogui.hscroll(clicks)
- 水平スクロールを行います。Excelなどの横に長い画面で有効です。
- 正の値: 右へスクロール
- 負の値: 左へスクロール

注意点

OS・アプリごとの感度の違い
- 引数 clicks の1単位がどれくらいスクロールするかは、OSの設定やアプリケーションによって大きく異なります。
- 「100」で1行しか動かないアプリもあれば、1画面分動くアプリもあります。必ずテストして調整してください。
マウスカーソルの位置
- コードを実行してもスクロールしない場合、マウスカーソルがスクロール対象のウィンドウ（メイン領域）の外にある可能性があります。
- moveTo() や click() で対象ウィンドウをアクティブにしてから実行するのが確実です。
Windowsでの横スクロール
- Windows環境では hscroll() が正しく動作しない（無視される）場合があります。
- その場合、Shiftキーを押しながら scroll() するなどの代替操作（keyDown('shift') + scroll()）が必要になることがあります。

応用

特定の座標にあるリストボックスやチャットログをスクロールさせる関数です。移動とスクロールをセットにします。

import pyautogui
import time

def scroll_target_area(target_x, target_y, amount):
    """
    指定した位置へマウスを移動し、そこにある要素をスクロールさせます。
    """
    pyautogui.FAILSAFE = True
    
    # 指定位置へ移動（移動しないと別の場所がスクロールしてしまうため）
    pyautogui.moveTo(target_x, target_y, duration=0.5)
    
    # 少し待機してフォーカスを安定させる
    time.sleep(0.2)
    
    # スクロール実行
    print(f"座標({target_x}, {target_y}) で {amount} スクロールします")
    pyautogui.scroll(amount)

if __name__ == "__main__":
    # 例: 画面中央付近を下にスクロール
    w, h = pyautogui.size()
    scroll_target_area(w // 2, h // 2, -500)