Python pyautoguiによるマウスカーソルの移動と位置取得

2025年9月19日

この記事では、Pythonのpyautoguiライブラリを使い、画面上のマウスカーソルをプログラムで制御するための基本的な関数、moveTo()、moveRel()、position()、size()について解説します。

画面の解像度を取得する

pyautoguiでマウスを正確に操作するには、まず画面のサイズ（解像度）を知る必要があります。pyautogui.size()関数は、画面の幅と高さをピクセル単位で返します。

座標系は、画面の左上が原点(0, 0)となります。

import pyautogui

# 画面の解像度を取得
screen_width, screen_height = pyautogui.size()

print(f"画面の幅: {screen_width}")
print(f"画面の高さ: {screen_height}")

マウスカーソルを移動する

マウスカーソルを移動させるには、主に絶対座標を指定するmoveTo()と、現在位置からの相対座標を指定するmoveRel()の2つの関数があります。

moveTo()：絶対座標への移動 moveTo(x, y)は、画面の左上を原点として、指定したx, y座標にカーソルを移動させます。duration引数を秒数で指定すると、その時間をかけてゆっくりと移動します。

import pyautogui

# 画面上で四角形を描くようにカーソルを移動させる
pyautogui.moveTo(100, 100, duration=0.5)
pyautogui.moveTo(400, 100, duration=0.5)
pyautogui.moveTo(400, 400, duration=0.5)
pyautogui.moveTo(100, 400, duration=0.5)

moveRel()：相対座標への移動 moveRel(x_offset, y_offset)は、マウスの現在位置を基準として、水平方向(x_offset)と垂直方向(y_offset)に指定したピクセル数だけカーソルを移動させます。

import pyautogui

# 現在位置から四角形を描くようにカーソルを移動させる
pyautogui.moveRel(200, 0, duration=0.5)   # 右に200px移動
pyautogui.moveRel(0, 200, duration=0.5)   # 下に200px移動
pyautogui.moveRel(-200, 0, duration=0.5)  # 左に200px移動
pyautogui.moveRel(0, -200, duration=0.5)  # 上に200px移動

現在のマウス座標を取得する

pyautogui.position()関数は、呼び出された時点でのマウスカーソルのx, y座標を返します。

import pyautogui
import time

print("10秒間、マウスの座標を追跡します。Ctrl-Cで終了。")
try:
    for i in range(10):
        # 現在の座標を取得して表示
        current_position = pyautogui.position()
        print(f"X: {current_position.x}, Y: {current_position.y}")
        time.sleep(1)
except KeyboardInterrupt:
    print("\n終了しました。")

このスクリプトは、1秒ごとに現在のマウスカーソルの座標をコンソールに出力します。

まとめ

pyautoguiによるマウス操作の基本は、size()で画面サイズを把握し、moveTo()で特定の座標へ、moveRel()で現在位置からの相対的な距離を移動させることです。また、position()を使えばいつでも現在のカーソル位置を取得できます。これらの関数を組み合わせることで、画面上の様々な要素を自動で操作する基礎ができます。

よかったらシェアしてね！