PyAutoGUIの基本

概要

PyAutoGUIとは、Pythonの自動化のためのパッケージです。
マウスを座標の位置の移動したり、画像を調査して移動したりキーボード操作をしたりするライブラリです。
pywinauto とか uiautomation などのGUI部品を取得して操作するツールと組み合わせるとより効果的に自動化が出来ます。

［主な機能］
マウス操作 : 指定座標への移動やクリックなど
キーボード操作 : 文字入力やショートカットキーの入力
メッセージボックス : メッセージボックスの表示
スクリーンショット : 画像の取得
等の機能があります。

この記事は、PyAutoGUIのドキュメントを参考に書いています。

Welcome to PyAutoGUI’s documentation! — PyAutoGUI documentation

pyautogui.readthedocs.io

テスト環境

Windows10
Python 3.12.5

MouseInfo==0.1.3
pillow==11.0.0
PyAutoGUI==0.9.54
PyGetWindow==0.0.9
PyMsgBox==1.0.9
pyperclip==1.9.0
PyRect==0.2.0
PyScreeze==1.0.1
pytweening==1.2.0

インストール

pip install pyautogui pillow

PyAutoGUIは、スクリーンショットを取得するのに pillowを使っています。
なので一緒にインストールしておくと便利です。

フェールセーフ

import pyautogui

pyautogui.write('gorillagorillagorilla', interval=1)

このスクリプトを実行してすべて表示する前にマウスを画面の4隅のどこかに移動してください。
そうするとプログラムは、途中で実行を停止します。

これは、自動実行中に何かあったときの安全機構で

import pyautogui

pyautogui.FAILSAFE = False

で、停止させることができます。
ですが普段はデフォルトで有効ですのでそのまま使ってください。

ポーズ

import pyautogui

pyautogui.PAUSE = 1

で、1秒実行を停止することができます。

マウス操作

画面の座標

画面の左上隅が(0,0)になります。
画面サイズが 1920×1080 の場合、座標は０から始まるので右下隅が (1919×1079)になります。
プログラムを書くときは、ツールを使って座標を取得するかPyAutoGUI自体をつかって座標を取得するかになります。
その時、この座標系を常に意識して使うことになります。

画面サイズの取得

import pyautogui
width, height = pyautogui.size()
print(f"{width}, {height}") # => 1920, 1080

これで画面サイズが取得できます。
中心を計算したり、画面端を知るのに必要になります。

マウス位置の取得

import pyautogui
width, height = pyautogui.position()
print(f"{width}, {height}") # => 252, 403

これで現在のマウスの位置を取得できます。
実際の画面でマウスを操作して座標を取得したり、リアルタイムに座標を取得することである範囲に入ったら動作を起こすなどトリガーなどとしても利用します。

XY座標の画面内判定

import pyautogui
pyautogui.onScreen(0, 0) # => True
pyautogui.onScreen(0, 99999) => False

座標が画面外にあるのか内にあるのかを判定します。
単純に、はみ出しているかの判定をするという事ですね。

マウスを動かす

import pyautogui
pyautogui.moveTo(800, 800)
pyautogui.moveTo(300, 300, 2)
pyautogui.move(100, 100, 2)
pyautogui.move(100, 0, 2)
pyautogui.move(100, None, 2)
pyautogui.move(500, 0, 5, pyautogui.easeInQuad)

moveTo(x, y) : 座標(x, y)へ移動
pyautogui.moveTo(800, 800) : 一瞬で座標(800,800)へ移動します。
pyautogui.moveTo(300, 300, 2) : 2秒かけて座標(300,300)へ移動します。

move(x, y) : 現在地から右へx、下へy移動します。
pyautogui.move(100, 100, 2) : 現在地から右へ100、下へ100, 2秒かけて移動します。
pyautogui.move(100, 0, 2) : 現在地から右へ100移動します。下へは、移動しません。
pyautogui.move(100, None, 2) : 上と同じになるとドキュメントにはありますが、下へ移動しますね。なんでだろ。
pyautogui.move(500, 0, 5, pyautogui.easeInQuad) : 第４引数でこれはだんだん移動速度が速くなる設定です。何種類か動き方を調節する設定があります。見栄えが必要ならこのような設定もいるのでしょうがあまり必要性を感じないので割愛。必要ならドキュメントを見てください。

マウスのクリック

import pyautogui

pyautogui.click()
pyautogui.click(x=100, y=200)
pyautogui.click(button='right')

pyautogui.click(clicks=2)
pyautogui.click(clicks=2, interval=1)
pyautogui.click(button='right', clicks=3, interval=1)

pyautogui.doubleClick()

pyautogui.click() : マウスを左クリックする
pyautogui.click(x=100, y=200) : 座標（100, 200)へ移動してから左クリック
pyautogui.click(button=’right’) : 右クリック

pyautogui.click(clicks=2) : 2回クリック
pyautogui.click(clicks=2, interval=1) : クリックの間隔を1秒開ける
pyautogui.click(button=’right’, clicks=3, interval=1) : すべて組み合わせられる

puautogui.doubleClick() : ダブルクリックする

他のも rightClick(), tripleClick() などの便利関数があるそうです。

マウスドラッグ

ドラッグは、マウスの動作を組み合わせて再現します。
マウスのクリックは、mouseDownとmouseUpの組み合わせでできています。

import pyautogui

pyautogui.mouseDown()
pyautogui.mouseUp()
pyautogui.mouseDown(button='right')
pyautogui.mouseUp(button='right', x=300, y=500)

pyautogui.mouseDown(button=’right’) : 右ボタンを押す
pyautogui.mouseUp(button=’right’, x=300, y=500) : 座標(300, 500)へ移動して右ボタンを離す

この2つの関数の組み合わせである位置から座標(300, 500)まで、ドラッグしたことになります。

スクロール

import pyautogui

pyautogui.scroll(50)
pyautogui.scroll(-50)
pyautogui.scroll(10, x=300, y=300)

pyautogui.hscroll(50)
pyautogui.vscroll(50)

pyautogui.scroll(50) : 縦スクロールします
pyautogui.scroll(-50) : マイナス方向へスクロール
pyautogui.scroll(50, x=300, y=300) : 座標へ移動してからスクロール

pyautogui.hscroll(50) : 水平スクロール。これはアプリによって機能しないかもしれません。いくつか試してみましたが機能するものはありませんでした。
pyautogui.vscroll(50) : scroll()と同じ縦スクロール。もしかしたらこれもアプリによっては機能しないのかも。試したところメモ帳では、スクロールしませんでした。

キーボード操作

文字入力

import pyautogui

pyautogui.write('Hello, Python!!\n')
pyautogui.write('Hello, Python!!', interval=1)

PyperClip

import pyautogui
import pyperclip

pyperclip.copy("こんにちは、パイソン！！")
pyautogui.hotkey('ctrl', 'v')

残念ながらPyAutoGUIでは、直接日本語は入力できません。
しかし、PyAutoGUIをインストールすると一緒に pyperclip インストールされるのでそれを使います。
pyperclip.copy(“こんにちは、パイソン！！”) : クリップボードに指定した文字列がコピーされます
pyautogui.hotkey(‘ctrl’, ‘v’) : クリップボードから ショートカットキー”Ctr+V”でカーソル位置に文字列をコピーします。
これで、日本語をカーソル位置に挿入することができます。

キーを押す

キーを押す( press() )ことは、キーを押し下げる( keyDown() )とキーを離す( keyUp() )とから成り立ちます。

import pyautogui

pyautogui.press("a")
pyautogui.press("enter")
pyautogui.press("f1")

いろんなキーが押せます。
以下が一覧です。

キー一覧

'\t', '\n', '\r', ' ', '!', '"', '#', '$', '%', '&', "'", '(',
')', '*', '+', ',', '-', '.', '/', '0', '1', '2', '3', '4', '5', '6', '7',
'8', '9', ':', ';', '<', '=', '>', '?', '@', '[', '\\', ']', '^', '_', '`',
'a', 'b', 'c', 'd', 'e','f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o',
'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '{', '|', '}', '~',
'accept', 'add', 'alt', 'altleft', 'altright', 'apps', 'backspace',
'browserback', 'browserfavorites', 'browserforward', 'browserhome',
'browserrefresh', 'browsersearch', 'browserstop', 'capslock', 'clear',
'convert', 'ctrl', 'ctrlleft', 'ctrlright', 'decimal', 'del', 'delete',
'divide', 'down', 'end', 'enter', 'esc', 'escape', 'execute', 'f1', 'f10',
'f11', 'f12', 'f13', 'f14', 'f15', 'f16', 'f17', 'f18', 'f19', 'f2', 'f20',
'f21', 'f22', 'f23', 'f24', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9',
'final', 'fn', 'hanguel', 'hangul', 'hanja', 'help', 'home', 'insert', 'junja',
'kana', 'kanji', 'launchapp1', 'launchapp2', 'launchmail',
'launchmediaselect', 'left', 'modechange', 'multiply', 'nexttrack',
'nonconvert', 'num0', 'num1', 'num2', 'num3', 'num4', 'num5', 'num6',
'num7', 'num8', 'num9', 'numlock', 'pagedown', 'pageup', 'pause', 'pgdn',
'pgup', 'playpause', 'prevtrack', 'print', 'printscreen', 'prntscrn',
'prtsc', 'prtscr', 'return', 'right', 'scrolllock', 'select', 'separator',
'shift', 'shiftleft', 'shiftright', 'sleep', 'space', 'stop', 'subtract', 'tab',
'up', 'volumedown', 'volumemute', 'volumeup', 'win', 'winleft', 'winright', 'yen',
'command', 'option', 'optionleft', 'optionright'

矢印キーや変換キーなども押せますね。

キーの同時押し

import pyautogui

pyautogui.keyDown("ctrl")
pyautogui.press("a")
pyautogui.press("b")
pyautogui.press("c")
pyautogui.keyUp("ctrl")

これは、”Ctrl”キーを押したまま”abc”と押してから”Ctrl”キーを離すという書き方です。

複数回と繰り返し入力

import pyautogui

pyautogui.press(['a', 'b', 'c'])
pyautogui.press("#", presses=10)

pyautogui.press([‘a’, ‘b’, ‘c’]) : “abc”と入力される
pyautogui.press(“#”, presses=10) :  “#”が１０文字入力される

import pyautogui

with pyautogui.hold("ctrl"):
    pyautogui.press("a")
    pyautogui.press("b")
    pyautogui.press("c")

先ほどの”キーの同時押し”の説明と同じ動作です。
“Ctrl”キーがおされ”abc”と入力されてから”Ctrl”が離されるキーの動作をします。

ホットキー

import pyautogui

pyautogui.hotkey("ctrl", "alt", "a")

これは、”Ctrl+Alt+A”同時押しなのですが
“Ctrl”->”Alt”->”A” の順に押して
“A”->”Alt”->”Ctrl” の順に離しているという事です。
pyautogui.hotkey(“ctrl”, “alt”, “a”, interval=1)などの様にすると遅延を入れられるとのことです。

メッセージボックス

alert() 関数

import pyautogui

pyautogui.alert(text='テストテキスト', title='テストタイトル', button='了解')

このコードを実行すると下のようなメッセージボックスが表示されます。
ボタンを押すと文字列”了解”が返ってきます。

confirm() 関数

import pyautogui

pyautogui.confirm(text='テストテキスト', title='テストタイトル', buttons=['了承', '取り消し'])

上のコードを実行すると下のようなメッセージボックスが表示されます。
“了承”を押すと文字列”了承”が、”取り消し”を押すと”取り消し”が返されます。

prompt() 関数

import pyautogui

pyautogui.prompt(text='テストテキスト', title='テストタイトル' , default='デフォルト')

コードを実行すると下のようなメッセージボックスが表示されます。
“OK”を押すとテキストボックスに入っていた文字列が返ってきます。”Cancel”を押すと”None”が返ってきます。

password() 関数

import pyautogui

pyautogui.password(text='テストテキスト', title='テストタイトル', default='12345', mask='x')

このコードを実行すると以下のようなメッセージボックスが表示されます。
テキストボックス内にパスワードを入力すると入力したテキストが返ってきます。

スクリーンショット機能

マウスを移動するときの座標を求めるための機能です。
小さな画像を元に画面上のどの場所にその小さな画像があるかを調べます。
たとえば何かのボタンの画像を元にそのボタンの位置を求めます。そして、その座標を元にマウスを移動しボタンを押すことができます。

PyScreezeというパッケージを使っていて、さらにそのパッケージはPillowを使っているとのことです。
PyScreezeは、PyAutoGUIをインストールしたときに一緒にインストールされるのですがPillowは別途インストールしてください。
pip install pillow
で、インストールできます。

Screenshot() と locateOnScreen() 関数

import pyautogui

im1 = pyautogui.screenshot(region=(0,0, 300, 400))
im2 = pyautogui.screenshot('search.png')

im1 = pyautogui.screenshot(region=(0,0, 300, 400))
とすると、regionで指定した領域の画像がスクリーンショットされて後から”im1″をそのまま保存せずに検索用の画像として使うことができます。

im2 = pyautogui.screenshot(‘search.png’)
これは、”search.png”として画面全体をスクリーンショット場合です。先ほどの様にregionをしてしてあげると検索用の画像がとして保存できます。

import pyautogui

try:
    im =pyautogui.locateOnScreen("start.png")
    print(im.left, im.top, im.width, im.height)
    print(pyautogui.center(im))
    x, y = pyautogui.center(im)
    pyautogui.click(x, y)
except Exception as e:
    print(e)
    print("not found")

テスト用画像

Window10の”スタート”メニューの画像を”start.png”として使いました。

このコードで画像の見つかった場所の中心を計算してクリックします。
結果、スタートメニューが開きます。

ドキュメントでは、画像が見つからない場合”None”を返すはずなのですが"None"も"ImageNotFoundException"も返さずただエラーになるだけでした。
もしかすると環境に依るのかもしれませんね。

画像の精度が悪い場合あいまいさを許容します。
pyautogui.locateOnScreen(“start.png”,  confidence=0.8)
とすると多少画像が違っていても検索できるようです。誤検索になる場合もあるので調節して使ってください。

※アクションゲームなどのBotとして使う場合等スピードが問題になる場合があります。
その場合は、検索する領域を限定してlocateOnScreen()を使うと対応できる場合があります。
pyautogui.locateOnScreen(“button.png”, region = (0, 0, 500, 500))　などとします。

グレースケールを使うこともわずかに早くなります。
pyautogui.locateOnScreen(“button.png”,  grayscale = True) とします。
だだし、誤検出が発生する場合があるとのことです。

locateAllOnScreen() 関数

for pos in pyautogui.locateAllOnScreen('button.png'):
    x,y = pyautogui.center(pos)
    pyautogui.click(x, y)

このコードである画像が画面上に複数ある場合、そのすべてを検索してクリックします。

ピクセルマッチ

画面内の指定した画素のRGBカラーを取得します。
おそらく、ボタンの色とか選択中の反転など画面の色が変更されたタイミングで何かをするなどの判断をするときに使うのかなと思います。

import pyautogui

im = pyautogui.screenshot()
rgb = im.getpixel((300, 500))
print(rgb)

座標(300, 500)のRGBを取得します。

import pyautogui

rgb = pyautogui.pixel(300,500)
print(rgb)

同様にRGBを取得します。

import pyautogui

equal_rgb = pyautogui.pixelMatchesColor(300, 500, (83, 221, 135))
print(equal_rgb)

これでRGBが一致なら”True”を　不一致なら”False”を返します。

この関数もあいまいさを許容して
pyautogui.pixelMatchesColor(300, 500, (83, 221, 135), tolerance=7)
とすると各色±7までの誤差を許容します。

PyAutoGUIと他ツールの比較・選択の視点

Pythonでデスクトップ操作を自動化する際には、目的や環境に応じて適切なツールを選ぶことが重要です。ここでは、私が実際に使い分けているPyAutoGUI、pywinauto、Selenium、uiautomationについて、使用例や適用シーンを交えて紹介します。

PyAutoGUI

• 特徴：PyAutoGUIは、画面の座標指定やマウス操作、スクリーンショットによる画像認識など、一般的なデスクトップ操作に強みがあります。システム設定変更やスクリーンキャプチャ、決まった座標でのクリック自動化など、日々の作業をルーチン化したい場面で役立っています。
• 使用場面：シンプルなスクリーンショット取得と保存が必要だったとき、また、特定のアプリケーションに依存せずに広範囲の操作が必要な場合に特に効果的でした。例えば、定期的にスクリーンショットを撮影し保存する自動化ができました。

pywinauto

• 特徴：pywinautoは、WindowsのGUI部品に直接アクセスでき、アプリの要素を操作できます。自分のシナリオでは、Windowsアプリのボタンや入力欄に直接アクセスし、複雑なクリック操作やデータ入力をスムーズに行うときに大いに役立ちました。
• 使用場面：Windows専用の業務アプリでの精密なボタン操作やデータの自動入力が求められる場合に活躍。例えば、インターフェースに要素が多く、ウィンドウ名やボタン名を指定するだけでピンポイントに操作できるため、繰り返し操作の短縮に貢献しました。

Selenium

• 特徴：SeleniumはWebブラウザ上での自動化に特化したツールで、Webアプリのボタンやテキストフィールドを直接操作することができます。HTML要素の取得や、JavaScript実行が可能で、実際に操作する感覚での操作ができます。

• 使用場面：自動でログインや、フォーム入力を繰り返す作業で非常に役立ちました。例えば、毎日の業務報告をWebアプリに投稿する自動化では、PyAutoGUIよりもSeleniumがHTMLベースの操作を確実に実行でき、効率的でした。

uiautomation

• 特徴：uiautomationは、WindowsのUI Automation APIを利用して、画面上の細かい要素を正確に取得・操作できるツールです。通常のマウス操作やキーボード入力に加え、ボタンの状態やテキストの内容を直接確認できるため、特定の要素を厳密に操作する自動化が可能です。
• 使ったシナリオ：システム設定画面や業務アプリの特定要素の取得と操作で使用しました。PyAutoGUIでは困難だった操作も、uiautomationならボタンや入力欄を直接操作できたため、精密な自動化を実現できました。

選択のポイントと感想

私は、まずPyAutoGUIで操作の範囲を大まかに確認した後、精密な要素操作が必要な場合にはpywinautoやuiautomationに切り替えるといった使い分けをしています。Web関連の操作は、Seleniumの方が素早くかつ確実にHTML要素を扱えるため、業務効率の向上に大いに貢献しています。

まとめ

まとめ

PyAutoGUIは、Pythonを使ってデスクトップ上の自動化を実現する強力なツールです。
座標を指定してのマウス操作や画像検索による位置指定、キーボード操作やスクリーンショットの取得が可能であり、他のGUI自動化ツールと組み合わせることでさらなる効率化が図れます。
自動化スクリプト作成時には、フェールセーフ機能や、ポーズや遅延などを活用して、安全で安定した操作ができます。

面白い活用方法などありましたらコメント欄にぜひ書き込んでくださいね。
参考にさせていただければと思います。