PyAutoGUI – Módulo de automatización multiplataforma

PyAutoGUI – Módulo de automatización multiplataforma

Actualizado el 23/09/2022.

PyAutoGUI es un módulo para automatizar tareas en múltiples sistemas operativos. «Automatizar» es generalmente entendido como controlar el mouse y el teclado, aunque en este caso en particular se incluyen otras herramientas como cuadros de diálogo y capturas de pantalla. Es similar a AutoPy.

La API del módulo es bastante simple, como veremos, aunque lamentablemente las funciones no siguen las nomenclaturas recomendadas por la guía de estilo del lenguaje.

Instalación

Puedes instalar PyAutoGUI junto con todas sus dependencias vía pip.

pip install pyautogui

Si tienes problemas instalando PyAutoGUI con pip, como alternativa puedes descargar el código de fuente, extraerlo y ejecutar en la terminal:

python setup.py install

Para poder ejecutar correctamente PyAutoGUI en Linux, además, deben instalarse las siguientes dependencias.

pip install python3-xlib
sudo apt-get install scrot
sudo apt-get install python3-tk
sudo apt-get install python3-dev

En Max OS se requiere lo siguiente:

pip install pyobjc-core
pip install pyobjc

En Windows el paquete no requiere ninguna instalación adicional.

Operaciones con el mouse

  • Obtener la posición del mouse:

    >>> import pyautogui
    >>> pyautogui.position()
    Point(x=913, y=444)
    

    El resultado es una tupla con nombre, por lo cual se puede acceder individualmente a las posiciones X e Y usando:

    >>> pos = pyautogui.position()
    >>> pos.x
    913
    >>> pos.y
    444
    

  • Mover el mouse a una posición determinada:

    >>> pyautogui.moveTo(300, 200)
    

    El código ubica el cursor en la posición X=300 Y=200, siendo el origen de coordenadas la esquina superior izquierda.

    Por defecto la transición ocurre instantáneamente. A través del parámetro duration podemos indicarle al módulo que el movimiento debe tomar una determinada cantidad de segundos.

    # Tomarse 3 segundos para mover el mouse.
    >>> pyautogui.moveTo(300, 200, 3)
    

    Además podemos configurar cómo debe realizarse la transición de la posición actual a la posición indicada, que por defecto se produce de forma lineal, vía un cuarto parámetro llamado tween. Las opciones son:

    • linear (valor por defecto)
    • easeInBack
    • easeInBounce
    • easeInCirc
    • easeInCubic
    • easeInElastic
    • easeInExpo
    • easeInOutBack
    • easeInOutBounce
    • easeInOutCirc
    • easeInOutCubic
    • easeInOutElastic
    • easeInOutExpo
    • easeInOutQuad
    • easeInOutQuart
    • easeInOutQuint
    • easeInOutSine
    • easeInQuad
    • easeInQueart
    • easeInQuint
    • easeInSine
    • easeOutBack
    • easeOutBounce
    • easeOutCirc
    • easeOutCubic
    • easeOutElastic
    • easeOutExpo
    • easeOutQuad
    • easeOutQueart
    • easeOutQuint
    • easeOutSine

     
    Por ejemplo:

    >>> pyautogui.moveTo(300, 200, 3, pyautogui.easeInBack)
    

    La función moveRel es similar a la anterior, pero los valores de X e Y se especifican en forma relativa a la posición actual del cursor, de modo que también pueden utilizarse valores negativos.

    # Mover el mouse arriba y a la derecha.
    >>> pyautogui.moveRel(50, -100, 1)
    
  • Simular un clic del mouse:

    >>> pyautogui.click()
    >>> pyautogui.doubleClick()
    >>> pyautogui.tripleClick()
    

    Las tres funciones operan por defecto con el clic izquierdo. Para cambiar esto indicamos el parámetro button que puede tomar los valores left (por defecto), middle o right.

    # Doble clic izquierdo.
    >>> pyautogui.doubleClick(button="right")
    

    También podemos indicar en qué posición de la pantalla debe efectuarse:

    >>> pyautogui.click(50, 100)
    

    De igual forma operan las funciones mouseUp y mouseDown, para generar una presión hacia arriba y otra hacia abajo, respectivamente.

    # Simula pyautogui.click().
    >>> pyautogui.mouseDown()
    >>> pyautogui.mouseUp()
    
  • Arrastrar y soltar (drag & drop):

    >>> pyautogui.dragTo(500, 400)
    

    Por defecto el mouse se arrastra manteniendo presionado el botón derecho. dragTo() acepta los mismos parámetros que click().

    Generalmente es recomendable que la operación no ocurra de inmediato para que funcione correctamente en todas las plataformas:

    # Recomendable.
    >>> pyautogui.dragTo(500, 400, duration=0.3)
    

    Para especificar la posición en términos relativos, usamos dragRel():

    >>> pyautogui.dragRel(100, 50)
    

    El método de arrastrar y soltar es básicamente similar a:

    pyautogui.mouseDown()
    pyautogui.moveTo(x, y)
    pyautogui.mouseUp()
    

    (Siempre y cuando no se indique el parámetro duration).

  • Desplazar el mouse (scroll):

    # Scroll hacia arriba.
    >>> pyautogui.scroll(400)
    # Scroll hacia abajo.
    >>> pyautogui.scroll(-400)
    

    El valor que debe pasarse a la función es sumamente dependiente de la plataforma, así que te recomiendo que pruebes algunos números arbitrarios para ver cuál se adapta a tus necesidades.

Operaciones con el teclado

  • Presionar y soltar una tecla:

    pyautogui.press("a")
    pyautogui.press("enter")
    
  • Escribir un texto:

    pyautogui.typewrite("Recursos Python")
    # "\n" provoca la presión de la tecla Enter.
    pyautogui.typewrite("Recursos\nPython")
    
  • Realizar combinaciones de teclas:

    # CTRL + F5.
    pyautogui.hotkey("ctrl", "f5")
    
  • Ver una lista de las teclas disponibles vía:

    >>> pyautogui.KEYBOARD_KEYS
    
  • Tanto typewrite() como hotkey() aceptan interval para indicar, en segundos, el intervalo entre una tecla y otra.

    pyautogui.typewrite("Recursos Python", interval=0.2)
    

Mensajes y cuadros de diálogo

PyAutoGUI incluye el módulo PyMsgBox, que permite crear mensajes y cuadros de diálogo utilizando internamente Tk.

# Desplegar un mensaje.
pyautogui.alert("¡Hola, mundo!", "Desde PyAutoGUI")

La función alert muestra un mensaje en pantalla con un título, y retorna el texto del botón presionado ("OK" por defecto) o bien None si se cerró la ventana. Para cambiar el texto del botón, añadimos un tercer argumento.

pyautogui.alert("¡Hola, mundo!", "Desde PyAutoGUI", button="Aceptar")

Si queremos que el mensaje muestre varias opciones hacemos uso de confirm():

# Botones.
OPT_CLOSE = "Sí, cerrar"
OPT_SAVE_AND_CLOSE = "Guardar todo y cerrar"
OPT_KEEP_WORKING = "No, seguir trabajando"

# Crear el mensaje.
opt = pyautogui.confirm(
    "¿Desea cerrar el programa?",
    "Confirmación",
    [OPT_CLOSE, OPT_SAVE_AND_CLOSE, OPT_KEEP_WORKING]
)

# Tomar decisión en base al botón presionado.
if opt == OPT_CLOSE:
    # ...
elif opt == OPT_SAVE_AND_CLOSE:
    # ...
elif opt == OPT_KEEP_WORKING:
    # ...

Para solicitar que el usuario ingrese un texto el módulo provee la función prompt.

# La función retorna None si se cerró la ventana o presionó "Cancel".
user = pyautogui.prompt("Ingrese su nombre de usuario", "Iniciar sesión")

Es posible indicar un valor por defecto y un tiempo límite en milisegundos, de modo que una vez transcurrido se cerrará el diálogo automáticamente.

# Valor por defecto "usuario1" y cerrar a los 5 segundos.
user = pyautogui.prompt("Ingrese su nombre de usuario", "Iniciar sesión",
                        default="usuario1", timeout=5000)

Capturas de pantalla

  • Capturar imagen de la pantalla:

    >>> screenshot = pyautogui.screenshot()
    

    Como PyAutoGUI trabaja internamente con Pillow, screenshot es una instancia de PIL.Image.Image.

  • Capturar una porción de la pantalla:

    >>> screenshot = pyautogui.screenshot(region=(50, 50, 400, 300))
    

    region es una tupla con la estructura (X, Y, Ancho, Alto).

  • Obtener el color de un píxel como una tupla (R, G, B):

    >>> screenshot.getpixel((500, 400))
    (225, 228, 229)
    

    Para saber si un píxel equivale a cierto color, puedes usar:

    >>> pyautogui.pixelMatchesColor(500, 400, (225, 228, 229))
    True
    

    Si bien este código es similar a screenshot.getpixel((500, 400)) == (225, 228, 229), tiene un ingrediente extra llamado tolerance que indica cuánto puede variar el color para que la búsqueda sea menos restrictiva.

    # El color no coincide exactamente pero es cercano.
    >>> pyautogui.pixelMatchesColor(500, 400, (220, 230, 232), tolerance=10)
    True
    

  • Ubicar una imagen dentro de la pantalla:

    # Retorna una tupla del tipo (X, Y, Ancho, Alto).
    >>> pyautogui.locateOnScreen("imagen.png")
    (759, 44, 96, 48)
    

    La función también acepta imagenes abiertas por Pillow:

    >>> from PIL import Image
    >>> image = Image.open("imagen.png")
    >>> pyautogui.locateOnScreen(image)
    (759, 44, 96, 48)
    

    Si la imagena aprece varias veces en la pantalla, locateAllOnScreen() retorna un iterador con todas las coincidencias:

    >>> list(pyautogui.locateAllOnScreen("imagen2.png"))
    [(1060, 629, 17, 20), (1177, 629, 17, 20)]
    
  • Ubicar una imagen dentro de una región de la pantalla:

    # También aplicable a locateAllOnScreen().
    >>> pyautogui.locateOnScreen("imagen.png", region=(0, 0, 1100, 300))
    (759, 44, 96, 48)
    

    Especificar una región aumenta considerablemente el tiempo de procesamiento de la función.

  • Ubicar una imagen teniendo en cuenta únicamente la escala de grises:

    # También aplicable a locateAllOnScreen().
    >>> pyautogui.locateOnScreen("imagen.png", grayscale=True)
    (759, 44, 96, 48)
    

    grayscale=True aumenta la velocidad de la función en alrededor de 30%.

Otras operaciones

  • Obtener el tamaño de la pantalla:

    >>> pyautogui.size()
    Size(width=1360, height=768)
    

    Igual que en el caso de la función position(), mencionada al principio, el resultado de size() es una tupla con nombre, por lo cual sus miembros se pueden acceder individualmente vía:

    >>> size = pyautogui.size()
    >>> size.width   # ancho
    1360
    >>> size.height  # alto
    768
    

  • Determinar si un par de coordenadas están dentro de los límites:

    >>> pyautogui.onScreen(100, 500)
    True
    >>> pyautogui.onScreen(1400, 700)
    False
    

Curso online 👨‍💻

¡Ya lanzamos el curso oficial de Recursos Python en Udemy! Un curso moderno para aprender Python desde cero con programación orientada a objetos, SQL y tkinter en 2024.

Consultoría 💡

Ofrecemos servicios profesionales de desarrollo y capacitación en Python a personas y empresas. Consultanos por tu proyecto.

18 comentarios.

  1. Ivan Garcia says:

    Hola, hay forma de realizar un clic sostenido por 3 segundos ? he visto que se pude usar dragTo() para arrastra manteniendo presionado el botón, pero no quiero arrastrar sino mantenerlo en un punto figo presionando por 3 segundos en boton izquierdo

  2. Gabriel Guerrero says:

    hola, amigo tengo una duda, sabes si usando esta libreria «pyautogui» programo un bot para alguna tarea en especifica, este funcione en un VPS? he intentado otros metodos como autohotkey el bot funciona muy bien pero al cerrar el escritorio remoto el programa de autohotkey se detiene

  3. franklin murillo says:

    hey que tall? interesante tu post de verdad.. quiero consultarte si me puedes dar idea con algo, quiero apagar la pantalla de mi laptop, cuando el puntero del mouse no este en la pantalla de dicha laptop, pues tengo 2 monitores conectados a ell, entonces, cuando el mouse ingrese al area de la pantalla esta encienda y cuando salga se apague

    • Recursos Python says:

      Hola. Entiendo que pyautogui no provee una solución para eso. Sí podés determinar la posición del mouse, pero para apagar una pantalla tendrás que usar la API de Windows. Es un poco complejo como para verlo en un comentario, podés pasar por el foro y crear un tema.

      Saludos

  4. Hola bro, buenísima información la que te haz tomado el tiempo de crear, estoy interesado en crear un programa para automatizar tareas del raton y teclado con sus respectivos hotkeys, pero lo que quiero es que primero replique mis movimientos, vi varias opciones de software unos de pago y otros gratuitos pero ninguno me satisfacio, las vi avanzadas para lo que yo quiero, como haria para que capte mis movimientos y los guarde sin necesidad de especificarle el lugar de la pantalla, podrias recomendarme librerias o por donde tengo que investigar para poder avanzar con este proyecto.

    • Recursos Python says:

      Hola, ¿cómo estás? Eso es un poco más avanzado. Con PyAutoGUI podés saber la posición del mouse y si una tecla está siendo presionada o no, pero no hay forma de hacer que te notifique cuando ocurre alguna de esas acciones para que vos lo puedas guardar o «grabar». Para eso deberías usar alguna librería como Interception, que está escrita en C. Se podría invocar desde Python usando ctypes o algún otro método, pero no es nada trivial.

      Saludos

  5. buen tutorial, gracias por compartir. Quiero automatizar un programa, que luego se va usar en otro computador y esto me puso a pensar, ya que probablemente la resolucion sea diferente y quiza las distancias entre los botones del software quiero automatizar esten mas alejados o mas cercanos.. ayer vi 2 resoluciones diferentes y creo que no hay problema siempre y cuando la diferencia no sea grande. Sabes algo al respecto ?

    muchas gracias

    • Recursos Python says:

      Hola. Es muy común que quieras enviar un evento a un botón, pero no sepas en qué posición está. La forma más sencilla (aunque a veces no suficiente) es utilizar las funciones relacionadas con la captura de pantalla para averiguar la posición del botón (o cualquier otro control) en cuestión. Después hay métodos más complejos pero precisos, como usar la API de Windows.

      Saludos

  6. Después de tratar de automatizar un proceso en el ordenador del trabajo con Pywinauto y no conseguirlo pues necesito permisos de administrador….probaré con esta librería, que creo cumplirá a la perfección.
    Me gustaría felicitaros por los artículos que publicáis…realmente es de 10.
    Saludos desde Bcn

  7. Hola, como puedo hacer para instalarlo para windows en el link que aparece en la parte de arriba aparecen muchas dependencias y no lo logro encontrar el correcto.

    • Recursos Python says:

      Hola, lo ideal sería vía pip install pyautogui que instalará todas las dependencias necesarias. ¿Estás obteniendo algún error?

      Saludos

  8. Buenos días,

    Por favor, ¿podrías indicarme cómo hacer para que el programa escriba correctamente el carácter «\»? La función typewrite() omite ese símbolo (también he probado con «\\». Puede que con la función hotkey() pero o no he sabido escribir bién el comando o tampoco funciona…

    Muchas gracias,
    Un saludo

Deja una respuesta