【Python】PyAutoGUIでマウス移動とドラッグ操作を完全制御する

2026年1月12日

概要

PyAutoGUIを使用して、マウスカーソルを意図した位置へ移動させたり、ドラッグ＆ドロップ操作をシミュレーションしたりする方法を解説します。

瞬時に移動させるだけでなく、duration パラメータを使って人間のような滑らかな動きを再現する方法や、絶対座標と相対座標の使い分けについても整理します。

仕様（入出力）

入力:
- 移動先のX, Y座標（整数）
- または、現在地からの移動距離（整数）
- 移動にかける時間（秒数・浮動小数点数）
出力:
- マウスカーソルの物理的な移動アクション
- 左ボタンを押したままのドラッグアクション
前提:
- pyautogui ライブラリがインストールされていること。

基本の使い方

指定した座標へ、指定した時間をかけてマウスを移動させる基本的なコードです。

import pyautogui

# 安全装置の設定（重要）
# マウスを画面の左上に移動させると強制停止します
pyautogui.FAILSAFE = True

# 画面の左上付近(200, 200)へ、2秒かけてゆっくり移動
pyautogui.moveTo(200, 200, duration=2.0)

コード全文

「絶対移動」で初期位置にセットした後、「相対移動」を使って四角形を描くようにカーソルを動かすデモコードです。

動作が分かりやすいように、各移動に duration を設定しています。

import pyautogui
import time

def demo_mouse_movements():
    """
    マウスの絶対移動と相対移動を組み合わせたデモを実行します。
    """
    # フェイルセーフ機能を有効化（マウスを左上隅にやると停止）
    pyautogui.FAILSAFE = True

    print("3秒後にマウス操作を開始します。中断するにはマウスを画面左上端へ移動してください。")
    time.sleep(3)

    try:
        # 1. 絶対移動 (moveTo)
        # 画面中央付近と思われる位置へ移動
        start_x, start_y = 500, 300
        print(f"初期位置へ移動: ({start_x}, {start_y})")
        pyautogui.moveTo(start_x, start_y, duration=1.0)

        # 2. 相対移動 (moveRel) で四角形を描く
        # 現在位置から見てどのくらい動かすかを指定します
        distance = 200
        speed = 1.0

        print("右へ移動中...")
        pyautogui.moveRel(distance, 0, duration=speed)
        
        print("下へ移動中...")
        pyautogui.moveRel(0, distance, duration=speed)
        
        print("左へ移動中...")
        pyautogui.moveRel(-distance, 0, duration=speed)
        
        print("上へ移動中...")
        pyautogui.moveRel(0, -distance, duration=speed)

        print("操作完了")

    except pyautogui.FailSafeException:
        print("\nフェイルセーフが発動しました。プログラムを緊急停止します。")

if __name__ == "__main__":
    demo_mouse_movements()

カスタムポイント

移動・ドラッグ関数の使い分け

PyAutoGUIには大きく分けて「移動」と「ドラッグ（クリックしたまま移動）」の2種類があり、さらにそれぞれ「絶対座標」と「相対座標」の指定方法があります。

関数名	動作タイプ	処理内容
pyautogui.moveTo(x, y)	移動（絶対）	画面左上を原点(0,0)とする指定座標へ移動する
pyautogui.moveRel(x, y)	移動（相対）	現在のマウス位置から、指定した距離だけ移動する
pyautogui.dragTo(x, y)	ドラッグ（絶対）	ボタンを押した状態で、指定座標へ移動する
pyautogui.dragRel(x, y)	ドラッグ（相対）	ボタンを押した状態で、現在のマウス位置から指定距離だけ移動する

durationパラメータの意味

すべての移動・ドラッグ関数には duration 引数を指定できます。

duration=0.0 (デフォルト):
- 瞬時にマウスカーソルが移動します。
- 人間には不可能な速度であるため、ボット検知に引っかかる可能性があります。
duration=数値 (例: 0.5, 2.0):
- 指定した秒数をかけて目的地へ移動します。
- 動きが滑らかになり、処理のステップを目視確認しやすくなります。

注意点

フェイルセーフ機能 (FAILSAFE)
- 自動操作中にプログラムが暴走すると、マウス操作ができず停止困難になる恐れがあります。
- pyautogui.FAILSAFE = True を設定しておくと、マウスを画面の四隅（デフォルトは左上）に強く押し込むことで例外 (FailSafeException) を発生させ、強制終了できます。必ず有効にしましょう。
画面解像度と範囲外エラー
- 指定した座標が画面サイズを超えている場合、例外が発生することがあります（OSによる）。
- pyautogui.size() で取得した範囲内に収めるようにしてください。
他のアプリへの干渉
- 意図しないウィンドウが前面にあると、そのウィンドウ上でクリックやドラッグが発生してしまいます。実行前にアクティブウィンドウを確認するロジックを入れると安全です。

応用

お絵描きソフトのキャンバス上で線を引くような操作を想定した、ドラッグ操作の実装例です。

dragRel を使うことで、開始位置に関わらず特定の形状を描画できます。

import pyautogui
import time

def draw_triangle_shape():
    """
    現在のマウス位置から三角形を描くようにドラッグ操作を行います。
    """
    pyautogui.FAILSAFE = True
    
    print("5秒以内にペイントソフト等のキャンバスを選択してください...")
    time.sleep(5)
    
    print("描画開始")
    
    # 1辺の長さ
    length = 150
    draw_speed = 0.5
    
    # 右下へドラッグ
    pyautogui.dragRel(length, length, duration=draw_speed, button='left')
    
    # 左へドラッグ
    pyautogui.dragRel(-length * 2, 0, duration=draw_speed, button='left')
    
    # 元の位置（右上）へ戻るようにドラッグ
    pyautogui.dragRel(length, -length, duration=draw_speed, button='left')
    
    print("描画終了")

if __name__ == "__main__":
    draw_triangle_shape()