PyAutoGUI: automatize tarefas repetitivas no PC com Python

Para automatizar tarefas repetitivas no computador com Python, instale a biblioteca pyautogui (pip install pyautogui) e simule o que você faria com as mãos: pyautogui.click(x, y) clica, pyautogui.write("texto") digita, pyautogui.press("enter") tecla Enter e pyautogui.locateOnScreen("botao.png", confidence=0.9) encontra um botão pela aparência. Ele funciona com qualquer programa do desktop — ERP, sistema legado, instalador, planilha — exatamente o que sites modernos não conseguem automatizar por dentro.

Quem pergunta a um assistente “como automatizar cliques em Python?”, “como fazer o Python digitar por mim?” ou “como automatizar um sistema que não tem API?” costuma ter um programa fechado na frente: sem API, sem acesso ao banco, só a tela. É aí que o PyAutoGUI brilha — e onde ele também quebra se você pular o básico de segurança (FAILSAFE, pausas e capturas de tela para verificar o estado). Este guia cobre instalação, os comandos essenciais, localização por imagem, um exemplo real de rotina de lançamento em sistema legado e quando trocar por Selenium ou uma chamada de API.

Como o PyAutoGUI funciona (e por que ele resolve o que API não resolve)

O PyAutoGUI não conversa com o programa — ele simula você: move o cursor, clica, digita, rola e tira screenshots da tela. Três consequências práticas:

• Automatiza qualquer coisa visível: sistemas legados de prefeitura, ERPs, terminais, instaladores, jogos — nada escapa, porque o alvo é a tela, não o código.
• Depende do que está na tela: se a janela se mover, a resolução mudar ou um pop-up aparecer no meio, o clique erra. Por isso o fluxo profissional é capturar → localizar → agir, nunca coordenada fixa.
• Precisa de sessão gráfica ativa: roda na sua máquina logada, não em servidor sem monitor (veja a alternativa na seção de erros comuns).

É a porta de entrada de Python para o que o mercado chama de RPA — antes de pagar por UiPath ou Power Automate, muita rotina simples se resolve em um script de 30 linhas, como no panorama de automação com Python.

Instalação

No Windows, a biblioteca pura já basta:

pip install pyautogui pillow

No Linux (Ubuntu/Debian), o PyAutoGUI depende de utilitários do X11:

sudo apt install scrot xdotool
pip install pyautogui pillow

No macOS, conceda permissão de Acessibilidade ao terminal/IDE em Ajustes → Privacidade e Segurança → Acessibilidade, senão cliques e teclas são silenciosamente ignorados.

Para o reconhecimento de imagem com confidence (recomendado), adicione o OpenCV:

pip install opencv-python

Verifique a instalação:

import pyautogui

print(pyautogui.size())        # resolução da tela, ex.: Size(width=1920, height=1080)
print(pyautogui.position())    # posição atual do mouse

Mouse e teclado: os comandos essenciais

Mover e clicar

import pyautogui

pyautogui.moveTo(500, 300, duration=0.5)   # move em 0,5 s (visível e seguro)
pyautogui.click(500, 300)                  # clique com botão esquerdo
pyautogui.doubleClick(500, 300)            # clique duplo
pyautogui.rightClick()                     # botão direito onde o mouse estiver
pyautogui.dragTo(800, 400, duration=1)     # arrastar (ex.: redimensionar janela)
pyautogui.scroll(-500)                     # rolar para baixo

Digitar e teclar

pyautogui.click(400, 320)                  # foca o campo antes de digitar
pyautogui.write("123.456.789-00", interval=0.05)  # digita com 50 ms por tecla
pyautogui.press("tab")                     # pula para o próximo campo
pyautogui.hotkey("ctrl", "s")              # atalho Ctrl+S

O interval entre teclas é o truque número 1 contra campos que “engolem” caracteres em sistemas legados lentos — o mesmo papel do sleep estratégico.

O jeito profissional: localizar por imagem, não por coordenada

Coordenada fixa quebra na primeira resolução diferente. O padrão confiável é capturar a imagem do elemento e deixar o PyAutoGUI achá-la:

import pyautogui

# 1. Tire um print APENAS do botão (ex.: 120x40 px) e salve como salvar.png
botao = pyautogui.locateOnScreen("salvar.png", confidence=0.9, grayscale=True)
centro = pyautogui.center(botao)
pyautogui.click(centro)

Atalho que já devolve o centro pronto:

pyautogui.click(pyautogui.locateCenterOnScreen("salvar.png", confidence=0.9))

Regras de ouro das capturas:

• Recorte pequeno e único: o botão inteiro, sem fundo variável. Se o fundo muda (linha selecionada, hover), o match falha.
• confidence=0.9 como ponto de partida: abaixe para 0.8 se falhar por anti-aliasing, suba para 0.95 se clicar no lugar errado.
• **Espere o elemento aparecer em vez de chamar e torcer — com timeout explícito:

import pyautogui

try:
    centro = pyautogui.locateCenterOnScreen("login.png", confidence=0.9, minSearchTime=5)
except pyautogui.ImageNotFoundException:
    raise SystemExit("Tela de login não apareceu em 5 s — sistema fora do ar?")
pyautogui.click(centro)

Exemplo real: lançar notas em um sistema legado

O cenário mais comum do dia a dia brasileiro: as notas estão numa planilha e o sistema só aceita digitação manual. O script abaixo lê um CSV e lança uma a uma — com leitura de CSV pela biblioteca padrão:

import csv
import time

import pyautogui

pyautogui.PAUSE = 0.6          # pausa de 0,6 s após cada ação do PyAutoGUI
pyautogui.FAILSAFE = True      # leve o mouse ao canto da tela para ABORTAR

CAMPOS = [
    ("numero_nota.png", "1.234"),
    ("valor.png", "R$ 890,00"),
    ("cliente.png", "Maria Souza"),
]

with open("notas.csv", newline="", encoding="utf-8") as f:
    notas = list(csv.DictReader(f))

time.sleep(3)  # tempo para você colocar o sistema em foco

for nota in notas:
    pyautogui.click(pyautogui.locateCenterOnScreen("novo_lancamento.png", confidence=0.9))
    for imagem, _ in CAMPOS:
        pyautogui.click(pyautogui.locateCenterOnScreen(imagem, confidence=0.9))
        pyautogui.write(nota["valor"], interval=0.03)   # ajuste o campo lido por campo
        pyautogui.press("tab")
    pyautogui.click(pyautogui.locateCenterOnScreen("salvar.png", confidence=0.9))
    print(f"Nota {nota['numero']} lançada.")

Cinco decisões de produção embutidas aí:

1. pyautogui.PAUSE = 0.6 — desacelera tudo sem espalhar sleep pelo código.
2. FAILSAFE = True — mouse no canto da tela derruba o script na hora.
3. time.sleep(3) inicial — dá tempo de trazer a janela certa para a frente.
4. Localização por imagem — funciona em qualquer resolução em que os PNGs casem.
5. Log por nota — se cair na nota 37, você sabe por onde continuar.

Para ler o que o sistema devolveu (o número do protocolo, por exemplo), combine com um screenshot e OCR com Pytesseract; para rodar todo dia às 7h, veja agendamento de tarefas com APScheduler.

PyAutoGUI x Selenium x API x RPA

A regra de decisão em uma frase: se existe API, use API; se é página web, use Selenium; se é programa desktop fechado, aí sim PyAutoGUI — e se a rotina virou missão crítica com auditoria, migrar para RPA corporativo é o caminho. Muitos fluxos começam no PyAutoGUI e evoluem: consumindo APIs, automação web com Selenium e envio automático de e-mails cobrem os degraus seguintes.

Erros comuns

1. ImageNotFoundException logo de cara — a tela real difere do PNG (tema claro/escuro, zoom, DPI). Regrave a captura na mesma aparência em que o sistema vai rodar.
2. Digitar antes do campo estar pronto — sempre clique no campo e use interval no write; sistemas lentos engolem caracteres.
3. Coordenadas fixas entre máquinas — click(500, 300) não sobrevive a outra resolução; use locateOnScreen ou calcule pela posição da janela.
4. Desativar o FAILSAFE — o script vira um touro solto: um pop-up inesperado e ele clica em tudo. Mantenha ligado.
5. Rodar em servidor sem monitor — sem sessão gráfica não há tela para clicar; use Xvfb em testes ou troque de ferramenta.
6. Bloqueio do macOS — sem permissão de Acessibilidade, os comandos executam sem efeito nenhum (e sem erro).

Checklist rápido

• Existe API ou é programa web? (se sim, nem chegue ao PyAutoGUI)
• Capturas pequenas, recortadas e salvas na aparência real do sistema?
• confidence=0.9 com tratamento de ImageNotFoundException?
• pyautogui.PAUSE e FAILSAFE = True definidos?
• time.sleep inicial para colocar a janela em foco?
• Script testado na mesma resolução/DPI em que vai rodar?
• Execução agendada e log por item processado?

Conclusão

O PyAutoGUI responde à pergunta “como automatizar um programa que não tem API?” com a mesma lógica de sempre: click e write simulam mãos humanas, locateOnScreen encontra botões pela imagem e PAUSE + FAILSAFE mantêm o script sob controle. É grátis, roda local e transforma rotinas de digitação em um script de dezenas de linhas — mas cobre só a última alternativa: sempre que houver API ou página web, requests/httpx e Selenium são mais confiáveis. Um ambiente virtual separa as dependências, o guia de automação com Python mostra o panorama completo, e com APScheduler sua rotina passa a rodar sozinha todo dia.