pyautogui 기본 사용법

1. PyAutoGUI란?

PyAutoGUI는

• 마우스 이동 및 클릭,
• Keyboard 입력,
• 스크린 캡처 및 단순한 화면 인식 등 다양한 기능을 제공하여
  반복적인 컴퓨터 작업을 자동화할 수 있는 Python 기반의 강력한 Automation Library임

공식 documentation Url: https://pyautogui.readthedocs.io/en/latest/index.html

 

참고로, macOS나 Linux에 비해 Windows에서 보다 유용한 기능이 먼저 나오는 편임.

• pyautogui.getActiveWindow()와 같이
• 현재 활성화된 windows의 위치를 얻어오는 기능이 2025.07 현재 Windows에만 가능함.
• 정확히는 Win32Window 객체를 얻어와서 이 객체로부터 위치 및 title 등의 정보를 attribute들을 통해 접근가능

 

참고: 비슷한 라이브러리-pynput

pynput은 Python에서 키보드와 마우스의 입력스트림을 모니터링하고 제어할 수 있게 해주는 크로스 플랫폼 라이브러리

• pynput은 입력 이벤트 모니터링에 특화된 반면,
• pyautogui는 스크린샷과 이미지 인식을 포함한 포괄적인 GUI 자동화에 더 적합
• 즉, 사용자 입력을 녹화하는 recorder나 key logger 구현에는 pynput이 보다 적합함.

official documentation url: https://pynput.readthedocs.io/en/latest/

---

주의: pyautogui의 자동화 수행을 중단시키는 방법

logout 으로 수행 중단

사용자가 logout하면 현재 실행되는 프로그램들이 모두 종료(shutdown)됨.

• logout short hand key:
  • Windows와 Linux의 경우 CTRL+ALT+DEL
  • macOS의 경우 cmd+SHIFT+Q

---

FailSafeException 이용 (PyAutoGUI가 제공하는 fail-safe feature)

• 모든 PyAutoGUI 함수 호출은 수행후 1/10 초 (pyautogui.PAUSE의 설정값) 정도의 pause를 가짐
• 이 시간을 이용하여 사용자는 마우스 커서를 화면의 4개의 코너로 이동시킬 수 있음.
• 사용자가 화면의 4개의 코너에 마우스 커서를 이동시키면,
• pyautogui 는 pyautogui.FailSafeException을 발생시킴.
• Puase duration은 pyautogui.PAUSE를 통해 seconds 단위로 설정 가능(float)
• pyautogui.FAILSAFE = False 로 이 기능의 비활성화 가능하나 추천하지 않음

다음은 FailSafeException을 사용해보려는 예제임.

수행하고 나서 5초 정도 이후에 마우스를 화면 왼쪽 위 코너로 이동시켜서 pyautogui.FailSafeException을 발생시켜 볼 것.

import pyautogui
import time

try:
    print("5초 후 마우스를 화면 왼쪽 위 모서리(0,0)로 이동하세요!")
    time.sleep(5)
    print("마우스 이동을 감지 중...")
    while True:
        pyautogui.move(10, 0)  # 마우스를 오른쪽으로 조금씩 이동
        time.sleep(0.1)
except pyautogui.FailSafeException:
    print("pyautogui.FailSafeException 발생: 마우스가 좌상단 (0,0) 근처에 도달했습니다.")

---

2. 기초 기능

2-1. Mouse 이동 및 click

마우스 커서의 이동 및 click 이벤트를 발생시킬 수 있음.

• pyautogui.moveTo(x, y, duration=0.5):
  • 화면의 x,y 절대좌표로 이동 (이동에 걸리는 시간 0.5초)
• pyautogui.move(x, y, duration=0.5):
  • 현재 위치 기준으로 오른쪽으로 x, 아래로 y 만큼 이동 (상대좌표, 이동에 걸리는 시간 0.5초)
• pyautogui.click(x, y, button='left' duration=0.5):
  • 화면의 x,y 절대좌표를 클릭 (클릭까지 걸리는 시간 0.5초)
  • button 생략시 좌클릭이나
  • 가급적 명시적으로 넣어줄 것.
• pyautogui.doubleClick(x, y, duration=0.5):
  • 화면의 x,y 절대좌표를 좌더블클릭 (클릭까지 걸리는 시간 0.5초)
• pyautogui.rightClick(x, y, duration=0.5):
  • 화면의 x,y 절대좌표를 우클릭 (클릭까지 걸리는 시간 0.5초)
• pyautogui.middleClick(x, y, duration=0.5):
  • 화면의 x,y 절대좌표를 미들클릭 (클릭까지 걸리는 시간 0.5초)
• pyautogui.dragTo(x, y, button='left', duration=0.5) :
  • 화면의 x,y 절대좌표로 드래그 (걸리는 시간 0.5초)
  • button 키워드 인자는 left, right, middle 중 하나의 값을 가짐.
• pyautogui.drag(x, y, button='left', duration=0.5) :
  • 현재 위치 기준으로 오른쪽으로 x, 아래로 y 만큼 드래그 (걸리는 시간 0.5초)
  • button 키워드 인자는 left, right, middle 중 하나의 값을 가짐.
• pyautogui.scroll( amount_to_scroll)
  • amount_to_scroll은 int 값으로
  • 양수(positive number)면 위로, 음수(negative number)면 아래로

아래 예제를 하기 전에 "3-2 마우스 커서 정보얻기"를 읽어볼 것:

2025.07.14 - [Python] - [Ex] PyAutoGUI - 마우스 이동 및 클릭

[Ex] PyAutoGUI - 마우스 이동 및 클릭

 

---

2-2. Keyboard 입력

Virtual Key Press 이벤트를 발생시킬 수 있음.

• pyautogui.write('Hello, pyautogui', 0.5)
  • 현재 활성화된 window의 focus가 놓인 text 입력 부분에 keyboard 입력.
  • Hello, pyautogui가 입력됨(둘러싸고 있는 single qutation은 제외)
  • 0.5 초의 delay 가 각 문자입력마다 놓임.
  • str 객체로 일반적인 입력을 처리하나, 특수 키등을 위해 list객체로 넘길 수도 있음.
    • 예: pyautogui.write(\['a','b','shiftleft','space',c'\], 0.5)
• pyautogui.KEYBOARD_KEYS를 통해 가능한 키보드 키들의 리스트를 확인가능함.

2025.07.14 - [Python] - [Ex] PyAutoGUI - 키보드 입력

[Ex] PyAutoGUI - 키보드 입력

 

---

2-3. 화면 캡쳐 및 이미지 인식

Pillow 객체를 이용하여, 캡쳐 및 pixel의 RGB값을 얻어옴.
OpenCV를 같이 설치한 경우 주어진 이미지 파일과 동일한 영역을 찾아내는 Image Recognition 기능을 활용할 때, confidence 옵션을 사용 가능.

이미지 인식의 정확도를 위해선
압축이 보통 이루어지는 jpg 계열보다는
png등의 포맷을 사용하길 권함.
동시에 openCV를 설치하고 사용할 것.

만약 Windows에서만 실행할 코드 작성의 경우엔,

pyautogui.locateOnScreen()과 같은 이미지 인식보다

pyautogui.getActiveWindow()를 이용한 현재 활성화된 창 또는

pyautogui.getWingowsWithTilte(title)과 같은 특정 타이틀의 창을 얻어오는 기능이 보다 권장됨

(아쉽게도 macOS에선 아직 사용가능하지 않음)

 

이같이 창(Window)를 이용하는 방식은 다음 문서를 참고할 것: 수정 중

 

다음은 화면인식을 이용한 함수들임:

• image = pyautogui.screenshot():
  • 화면을 캡쳐함.
  • 반환되는 객체는 Image객체ㅣ;
• img_color = pyautogui.pixel(x,y):
  • 특정 위치의 pixel의 RGB값을 가진 튜플 객체를 반환.
  • img_color은 (R,G,B)임.
• bool_val = pyautogui.pixelMatchesColor(x, y, target_color):
  • target_color은 (R,G,B)인 튜플객체로,
  • x,y의 pixel값이 이와 같으면 True를 반환.
  • 아니면 False를 반환.
• box = pyautogui.locateOnScreen(img_file_path):
  • img_file_path와 정확히 일치하는 위치를 named tuple 객체 (Box)로 반환.
    • confidnece 옵션을 통해 화면과 완벽하게 일치하지 않더라도 어느정도 유사한지를 지정하여 찾을 수 있음.
    • cv2.matchTemplate()에 기반한 similarity의 threshold값을 confidence로 지정가능
    • confidence 는 [0.0 ,1.0]의 값으로 지정.
    • 기본은 None으로 confidence=1.0과 같음
  • box는 Box라는 이름의 named tuple객체로 left, top, width, height attribute를 가짐.
  • 정확히 일치하는 영역이 없을 경우, ImageNotFoundException을 raise.
  • 일부 이전 버전은 None을 반환하는 것이 기본으로 되어 있으니 확인하고 사용할 것.
    • ImageNotFoundException을 대신 사용하려면, pyautogui.useImageNotFoundException()을 미리 호출할 것.
  • 인자로 넘겨지는 이미지와 같은 영역이 여러 개 있는 경우엔 locateAllOnScreen()을 사용할 것.
• gen = pyautogui.locateAllOnScreen(img_file_path):
  • img_file_path와 정확히 일치하는 복수의 위치를 iterate 시킬 수 있는 generator객체를 반환.
  • l = list(gen) 등을 통해 list로 만들면, 일치하는 위치에 대한 x,y,w,h로 구성된 튜플 객체를 item으로 가지는 리스트 객체를 얻음.

pyautogui.locateOnScreen의 경우
dpi등의 차이로 인해 이미지의 size가 다른 경우는
다른 이미지로 판정함.

confidence도 pixel값 간의 미세한 차이를 용인하는 것이지 이미지의 가로 세로 scale의 차이를 고려하진 못함.
크기 차이 등을 고려하려면, OpenCV를 직접 사용하거나, DL 기반의 Image Location을 사용해야 함.

 

간단한 예제

import pyautogui

# 특정 이미지가 화면 어딘가에 있을 때 위치 탐색
location = pyautogui.locateOnScreen('target.png', confidence=0.8)

if location:
    # 이미지의 중앙 좌표 계산
    center = pyautogui.center(location)
    print(f"이미지 위치: {center}")

    # 해당 위치로 마우스 이동
    pyautogui.moveTo(center.x, center.y, duration=0.5)

    # 필요하다면 클릭도 수행 가능
    pyautogui.click()
else:
    print("이미지를 찾을 수 없습니다.")

2025.07.15 - [Python] - [Ex] PyAutoGUI - 화면 캡처 및 이미지 인식

[Ex] PyAutoGUI - 화면 캡처 및 이미지 인식

 

---

2-4. Hotkey 입력

아래의 기타 기능에서 다루는 keyDown과 keyUp을 이용하는 방법도 있으나 pyautogui.hotkey()를 권장함

• 특수키등의 지정을 할때나 누를 키는 소문자로 표시.
• 대문자 입력이 필요하면, shift 키와 함께 처리: pyautogui.hotkey('shift', 'a') # 대문자 'A' 입력

예: 복사를 위한 CTRL+C는 다음으로 처리가능.

pyautogui.hotkey('ctrl', 'c')

# pyautogui.keyDown('ctrl')
# pyautogui.keyDown('c')
# pyautogui.keyUp('c')
# pyautogui.keyUp('ctrl')

2025.07.15 - [Python] - [Ex] PyAutoGUI - hotkey 조합 입력하기

[Ex] PyAutoGUI - hotkey 조합 입력하기

---

참고: 키를 나타내는 문자열 표

키 문자열 (Key String)	의미 (Meaning)
'a', 'b', '1', '%' 등	일반 문자 및 숫자 키
'enter', 'return', '\n'	엔터(Enter) 키
'esc'	ESC 키
'shiftleft', 'shiftright'	좌/우 SHIFT 키
'altleft', 'altright'	좌/우 ALT 키
'ctrlleft', 'ctrlright'	좌/우 CTRL 키
'tab', '\t'	TAB 키
'backspace', 'delete'	백스페이스 및 삭제 키
'pageup', 'pagedown'	페이지 업/다운 키
'home', 'end'	HOME / END 키
'up', 'down', 'left', 'right'	방향키 (↑ ↓ ← →)
'f1' ~ 'f12'	F1 ~ F12 함수 키
'volumemute', 'volumedown', 'volumeup'	볼륨 음소거 / 줄이기 / 높이기 키
'pause'	일시정지(PAUSE) 키
'capslock', 'numlock', 'scrolllock'	CAPS, NUM, SCROLL LOCK 키
'insert'	INSERT (INS) 키
'printscreen'	프린트 스크린 키
'winleft', 'winright'	윈도우 키 (Windows 전용)
'command'	Command(⌘) 키 (macOS 전용)
'option'	Option(⌥) 키 (macOS 전용)
'space'	스페이스(공백) 키
'apps'	앱 메뉴(우클릭) 키 (일부 키보드에서 지원)

---

3. 기타 기능

3-1. Message Box사용하기

PyMsgBox에 기반한 TkInter를 이용한 Message Box 기능을 지원함.

단, Python의 공식 iteractive shell에서만 제대로 동작하고, IPython 및 IPython 기반의 shell에선 정상동작하지 않으니 주의할 것.

TkInter 계열은 IPython 계열과 궁합이 매우 안좋음.

지원하는 함수는 다음과 같음:

• pyautogui.alert(text) : 메시지를 표시하고 확인 버튼 하나만 있는 알림 창을 띄움. 'OK' 가 반환
• pyautogui.confirm(text) : 메시지와 함께 확인/취소 버튼이 있는 창을 띄우고, 클릭한 버튼의 이름을 문자열 ('OK' 또는 'Cancel')로 반환.
• pyautogui.prompt(text) : 메시지와 함께 입력 필드를 제공하고, 사용자가 입력한 문자열을 반환 (취소시 None반환).
• pyautogui.password(text) : 입력 필드에 입력한 내용을 별표(*)로 가려서 비밀번호 등의 민감한 정보를 입력받음. 나머진 prompt와 같음.

2025.07.15 - [Python] - [Ex] PyAutoGUI - MessageBox

[Ex] PyAutoGUI - MessageBox

---

3-2. 마우스 커서 정보 얻기

pyautogui.mouseInfo()를 사용할 경우, 현재 마우스 커서의 좌표(x, y)와 해당 위치 픽셀의 색상(RGB)을 실시간으로 확인할 수 있는 작은 창을 확인할 수 있음.이는 PyAutoGUI에 포함된 유틸리티 중 하나임.

macOS에서는 실행권한 설정을 하지 않은 경우, 정상 동작 하지 않을 수 있음.
실행할 terminal에 스크린캡쳐 권한을 줘야 함.

pixel의 RGB는 macOS에서는 python이 실행되는 terminal등에 "화면 녹화 권한"을 준 경우에도 얻을 수 없음:

•  "NA_on_macOS" 로 뜸: Not Available
• macOS 13 Ventura 이상 및 Intel CPU가 아닌 경우 동작 안함.
• macOS의 NSApplication은 macOS의 AppKit 프레임워크에 속한 Objective-C 클래스를 가리킴.

---

3-3. 마우스 기본 입력

• pyautogui.position()
  • 현재 마우스 커서의 화면 좌표를 (x, y) 형태의 named tuple Point 객체로 반환
  • Point 는 x, y를 attribute로 가짐
• pyautogui.mouseDown(), pyautogui.mouseUp()
  • mouseDown()은 마우스 버튼을 누른 상태로 유지하는 동작을 시뮬레이션.
  • mouseUp(): 눌린 마우스 버튼을 떼는 동작을 시뮬레이션.
  • x,y, button 를 통해 세부 조정 가능.

import pyautogui

# 마우스 왼쪽 버튼을 누르고 유지
pyautogui.mouseDown(x=100, y=200, button='left')

# ... 드래그할 수 있는 작업 수행 ...

# 마우스 버튼을 떼기
pyautogui.mouseUp(button='left')

---

3-4. 키보드 기본 입력

• pyautogui.keyDown(key), pyautogui.keyUp(key)
  • keyDown(key)은 특정 키를 누른 상태로 유지하는 동작을 시뮬레이션.
  • keyUp(key)은 눌린 키를 떼는 동작을 시뮬레이션.
  • key 인자를 통해 'shift', 'ctrl', 'a', 'enter' 등 다양한 키를 지정 가능.
• pyautogui.press()
  • 지정한 키를 한 번 누르고 떼는 동작을 자동으로 수행.
  • key 인자에 'enter', 'space', 'tab', 'a', '1' 등 키를 나타내는 문자열을 지정.
  • press()는 keyDown() 이후 keyUp()을 자동으로 실행하는 함수임.
  • press(keys, presses=N) 형태로 여러 번 누르기도 가능.

import pyautogui

# Shift 누른 상태에서 A 입력 (대문자 A)
pyautogui.keyDown('shift')
pyautogui.press('a')
pyautogui.keyUp('shift')

# Enter 키 3번 누르기
pyautogui.press('enter', presses=3)

---

3-5. 화면 정보 얻기

PyAutoGUI는 주로 "주모니터(main monitor")를 기반으로 적용하는 것을 추천함.

 

• size = pyautogui.size()
  • 화면 크기 정보를 가지는 Size 라는 named tuple의 객체를 반환.
  • Size는 width와  height를 attribute로 가짐.

---

같이보면 좋은 자료들

2025.04.04 - [Python] - [Py] collections.namedtuple-Factory Function

[Py] collections.namedtuple-Factory Function

 

2025.07.14 - [Python] - [Ex] Input_Recoder and Replayer

[Ex] Input_Recoder and Replayer

---