---
title: "PyAutoGUI: automatize tarefas repetitivas no PC com Python"
url: "https://python.dev.br/blog/pyautogui-automacao-tarefas-repetitivas-python/"
markdown_url: "https://python.dev.br/blog/pyautogui-automacao-tarefas-repetitivas-python.MD"
description: "Aprenda PyAutoGUI em Python: controle mouse e teclado, localize imagens na tela e automatize tarefas repetitivas com failsafe. Tabela PyAutoGUI, Selenium e API."
date: "2026-10-03"
author: "Equipe Python Dev BR"
---

# PyAutoGUI: automatize tarefas repetitivas no PC com Python

Aprenda PyAutoGUI em Python: controle mouse e teclado, localize imagens na tela e automatize tarefas repetitivas com failsafe. Tabela PyAutoGUI, Selenium e API.


**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](/blog/python-e-selenium-automacao-web/) ou uma chamada de [API](/blog/python-e-apis-consumindo-dados/).

## 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](/blog/automatizacao-com-python/).

## Instalação

No Windows, a biblioteca pura já basta:

```bash
pip install pyautogui pillow
```

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

```bash
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:

```bash
pip install opencv-python
```

Verifique a instalação:

```python
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

```python
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

```python
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:

```python
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:

```python
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:

```python
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](/blog/python-csv-leitura-escrita-arquivos/) pela biblioteca padrão:

```python
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](/blog/python-ocr-extrair-texto-imagem-pytesseract/); para rodar todo dia às 7h, veja [agendamento de tarefas com APScheduler](/blog/apscheduler-agendar-tarefas-python/).

## PyAutoGUI x Selenium x API x RPA

| Situação | Ferramenta certa | Por quê |
|---|---|---|
| Programa desktop sem API (ERP, legado) | PyAutoGUI | Só a tela está disponível; simula o humano |
| Site / sistema web | Selenium ou Playwright | Acha elementos por seletor, roda headless, não depende de posição |
| Sistema com API/documentação | requests ou httpx | Rápido, confiável, sem interface — sempre a primeira opção |
| Processo corporativo com auditoria e fila | RPA corporativo (UiPath, Power Automate) | Governança, retries gerenciados e suporte de fornecedor |

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](/blog/python-e-apis-consumindo-dados/), [automação web com Selenium](/blog/python-e-selenium-automacao-web/) e [envio automático de e-mails](/blog/python-para-automacao-de-emails/) 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](/blog/python-e-apis-consumindo-dados/) e [Selenium](/blog/python-e-selenium-automacao-web/) são mais confiáveis. Um [ambiente virtual](/guias/criando-virtual-environment/) separa as dependências, o guia de [automação com Python](/blog/automatizacao-com-python/) mostra o panorama completo, e com [APScheduler](/blog/apscheduler-agendar-tarefas-python/) sua rotina passa a rodar sozinha todo dia.