PyAutoGUI: o que é, como instalar, como usar e principais funcionalidades | Alura Cursos Online
PyAutoGUI: o que é, como instalar, como usar e principais funcionalidades
11 min11 minutos de leitura
11 min11 minutos de leitura
Autor(a)
Mike de Sousa
Olá, me chamo Mike de Sousa. Atuo como Suporte Educacional aqui na Alura, onde tenho a oportunidade de aprender ainda mais enquanto ajudo outras pessoas em sua jornada. Tenho um foco especial em Front-end, explorando React e TypeScript, mas estou sempre em busca de novos conhecimentos e desafios. Fora da programação, gosto de jogar RPG de mesa, explorar novas ideias e deixar a criatividade fluir.
Inscreva-se em nossa Newsletter
Fique por dentro de conteúdos, insights e oportunidades do universo tech. Receba novidades e lançamentos direto no seu e-mail.
PyAutoGUI é uma biblioteca Python que permite controlar o mouse e o teclado do computador de forma programática, simulando o que você faria manualmente, só que de forma automática e muito mais rápida.
Se você já se pegou repetindo a mesma sequência de cliques e digitações várias vezes ao dia, esse artigo foi feito para você.
Imagina ter um assistente digital que abre programas, preenche formulários, tira prints e clica em botões, tudo enquanto você toma um café. É assim que o PyAutoGUI atua: ele age como se fosse uma “mão virtual” que controla o computador no lugar da pessoa desenvolvedora.
Nesse guia, você vai aprender o que é o PyAutoGUI, para que ele serve, quais são suas principais funcionalidades, como instalar e começar a usar na prática.
O que é PyAutoGUI?
PyAutoGUI é uma biblioteca open source para Python criada por AI Sweigart, autor do famoso livro “Automate the Boring Stuff with Python".
Ela permite que scripts Python controlem o mouse e o teclado para automatizar interações com outros aplicativos, como se uma pessoa estivesse usando o computador.
O nome é uma junção de “Python” + “AutoGUI”, aonde GUI vem de Graphical User Interface, ou seja, Interface Gráfica do Usuário. Em termos práticos, qualquer coisa que você vê na tela e pode clicar ou digitar, o PyAutoGUI consegue fazer por você.
Diferente de ferramentas como Selenium, que é focada em automação de navegadores web, o PyAutoGUI trabalha no nível do sistema operacional, controlando a interface gráfica de qualquer aplicativo, seja um editor de texto ou uma planilha, por exemplo.
O PyAutoGUI serve para automatizar qualquer tarefa que envolva interação com a interface gráfica do computador. Na prática, ele é muito útil em situações como:
Tarefas repetitivas no trabalho: preencher formulários, copiar dados de um sistema para outro, gerar relatórios diários.
Testes de software: simular ações de usuário para testar interfaces gráficas de aplicativos.
Captura de tela: tirar screenshots periódicos.
Em resumo, sempre que você se deparar com uma tarefa manual e repetitiva que envolve clicar, digitar ou navegar por telas, o PyAutoGUI pode ser a solução ideal.
Como funciona o PyAutoGUI?
O PyAutoGUI funciona enviando comandos diretamente ao sistema operacional para simular eventos de mouse e teclado.
Quando você chama, por exemplo, pyautogui.click(200, 300), a biblioteca instrui o SO a mover o cursor para as coordenadas (200, 300) da tela e registrar um clique, exatamente como se você tivesse feito isso com a mão.
O sistema de coordenadas usado é simples: a tela é tratada como um plano cartesiano onde o ponto (0, 0) fica no canto superior esquerdo. O eixo X aumenta para a direita, e o eixo Y aumenta para baixo. Então, para clicar no centro de uma tela de 1920x1080 pixels, você usaria as coordenadas (960, 540).
Além disso, o PyAutoGUI conta com um sistema de segurança chamado Fail-Safe.
Por padrão, se o cursor do mouse for movido para qualquer um dos quatro cantos da tela, a biblioteca lança uma exceção FailSafeException e interrompe a execução do script.
Isso é extremamente útil para evitar que um script fora de controle cause danos, é um “botão de emergência” inteligente.
Como instalar o PyAutoGUI?
A instalação é simples e feita via pip. Abra o terminal ou prompt de comando e execute:
As dependências variam de acordo com o sistema operacional:
Windows: o PyAutoGUI já funciona após a instalação com pip, sem dependências adicionais.
macOS: pode ser necessário instalar pyobjc-core e pyobjcvia pip. Também é preciso conceder permissões de acessibilidade ao terminal nas configurações de privacidade do sistema.
Linux: requer python3-tk, python3-dev e scrot para funcionalidade de screenshot. Instale com: sudo apt-get install python3-tk python3-dev scrot.
Após a instalação, o uso é bastante direto, basta importar a biblioteca no início do script:
import pyautogui
# Verificar tamanho da tela
largura, altura = pyautogui.size()
print(f'Resolução: {largura}x{altura}')
Quais as principais funcionalidades do PyAutoGUI?
O PyAutoGUI oferece um conjunto de funcionalidades que cobrem a maioria dos casos de automação de interface gráfica.
Movimentação e cliques no mouse
Você pode mover o cursor para qualquer posição da tela, realizar cliques simples, duplos ou com o botão direito, arrastar elementos e até rolar o scroll. Vou listar abaixo alguns exemplos:
pyautogui.moveTo(100, 150)
# Move o mouse para as coordenadas
pyautogui.click()
# Clica na posição atual
pyautogui.click(200, 300)
# Move e clica
pyautogui.doubleClick(200, 300)
# Clique duplo
pyautogui.rightClick(200, 300)
# Clique com botão direito
pyautogui.scroll(10)
# Rola a tela para cima
pyautogui.drag(100, 0, duration=1)
# Arrasta o mouse 100px para a direita
O parâmetro durationdefine quantos segundos o movimento leva, o que deixa a automação mais natural e menos agressiva.
Digitação de texto
O PyAutoGUI permite simular a digitação de qualquer texto. A função write() digita caractere por caractere, enquanto o parâmetro interval controla a pausa entre cada tecla:
pyautogui.write('Oi, Alura!', interval=0.05)
# Digita com pausa de 0,05s entre cada letra
Mas atenção: a função write() funciona bem para textos em inglês (ASCII). Para caracteres especiais como acentos, é recomendável usar o pyperclip para copiar o texto para a área de transferência e depois colá-lo com pyautogui.hotkey(‘ctrl’, ‘v’).
import pyautogui
import pyperclip
import time
# Texto com acentos e caracteres especiais
texto = "Olá, como você está? Ação, coração, atenção!"# Copia o texto para a área de transferência
pyperclip.copy(texto)
# Aguarda 2 segundos (tempo para você clicar no campo desejado)
time.sleep(2)
# Cola o texto com Ctrl+V
pyautogui.hotkey('ctrl', 'v')
print("Texto colado com sucesso!")
Captura de Tela
A biblioteca permite tirar screenshots de toda a tela ou de uma região específica com a função screenshot():
screenshot = pyautogui.screenshot()
screenshot.save('minha_captura.png')
# Captura de região específica: (x, y, largura, altura)
regiao = pyautogui.screenshot(region=(0, 0, 1500, 1200))
regiao.save('regiao.png')
Localização de imagens
Você também pode fornecer uma imagem (por exemplo, a foto de um botão) e a biblioteca procura onde ela está na tela:
# Encontra a posição de um botão na tela
posicao = pyautogui.locateOnScreen('botao_salvar.png')
pyautogui.click(posicao) # Clica no local encontrado
Há também a função locateCenterOnScreen(), que retorna diretamente as coordenadas do centro da imagem encontrada, muito prático para clicar em elementos visuais sem precisar conhecer suas coordenadas fixas.
Pressionamento de teclas e atalhos
Para pressionar teclas individuais ou combinações, o PyAutoGUI oferece as funções press() e hotkey():
pyautogui.press('enter') # Pressiona Enter
pyautogui.press('esc') # Pressiona Escape
pyautogui.hotkey('ctrl', 'c') # Copia (Ctrl+C)
pyautogui.hotkey('ctrl', 'v') # Cola (Ctrl+V)
pyautogui.hotkey('alt', 'f4') # Fecha janela # Segurar uma tecla enquanto pressiona outras with pyautogui.hold('shift'):
pyautogui.press(['left', 'left', 'left']) # Shift + setas
Caixas de diálogo e mensagens
O PyAutoGUI inclui funções para exibir caixas de diálogo simples durante a execução de um script, úteis para interagir com a pessoa usuária ou confirmar ações:
pyautogui.alert('Operação concluída!')
# Exibe alerta
pyautogui.confirm('Deseja continuar?')
# Confirmação OK/Cancel
nome = pyautogui.prompt('Qual é o seu nome?')
# Entrada de texto
senha = pyautogui.password('Digite sua senha:')
# Entrada oculta
Essas funções pausam a execução do script até que a pessoa interaja com a caixa de diálogo, excelente para scripts que precisam de confirmação antes de realizar ações irreversíveis.
Exemplos de uso e casos práticos
Para palpabilizar o uso do PyAutoGUI, trouxemos alguns exemplos de uso e casos práticos para análise:
Preenchimento automático de formulário
Imagine que você precisa preencher o mesmo formulário todo dia com informações de uma planilha. Com o PyAutoGUI você pode automatizar esse processo:
import pyautogui
import time
# Aguarda 2 segundos para você posicionar o cursor no campo
time.sleep(2)
# Clica no campo de nome e digita
pyautogui.click(400, 300)
pyautogui.write('Maria da Silva', interval=0.05)
# Vai para o próximo campo (Tab) e digita o email
pyautogui.press('tab')
pyautogui.write('[email protected]', interval=0.05)
# Confirma com Enter
pyautogui.press('enter')
Tirar screenshots periódicos
Para monitorar mudanças em uma aplicação ao longo do tempo, você pode capturar a tela em intervalos regulares:
import pyautogui
import time
from datetime import datetime
for i inrange(10): # Captura 10 screenshots
timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
pyautogui.screenshot(f'captura_{timestamp}.png')
time.sleep(60) # Espera 1 minuto
Clicar em botão por imagem
Esse exemplo mostra como localizar e clicar em um botão usando uma imagem de referência, sem precisar de coordenadas fixas:
import pyautogui
# Procura o botão 'Salvar' na tela local = pyautogui.locateCenterOnScreen('botao_salvar.png', confidence=0.9)
iflocal:
pyautogui.click(local)
print('Botão encontrado e clicado!')
else:
print('Botão não encontrado na tela.')
O parâmetro confidence (disponível com a biblioteca opencv-python) define o nível de correspondência aceito, valores próximos a 1.0 são mais rigorosos.
Cuidados e limitações do PyAutoGUI
Apesar de ser uma ferramenta incrível, o PyAutoGUI tem algumas limitações importantes que você precisa conhecer antes de colocá-lo em produção:
Dependente da resolução e layout da tela: scripts baseados em coordenadas fixas podem quebrar se a resolução mudar ou se a janela for redimencionada.
Não funciona em modo headless: o PyAutoGUI exige uma interface gráfica ativa. Não funciona em servidores sem display ou ambientes CLI puros.
Velocidade pode afetar a confiabilidade: scripts muito rápidos podem “passar” por elementos antes que a interface carrega. Use time.sleep() estrategicamente.
Não funciona em Android ou iOS: a biblioteca é exclusiva para desktops com Windows, macOS ou Linux.
Boas práticas para usar o PyAutoGUI
Documente seu código: scripts de automação tendem a ser frágeis, comentários ajudam na manutenção.
Teste em ambiente controlado: antes de rodar em produção, teste o script várias vezes em ambiente de desenvolvimento.
Adicione tratamento de erros: use try/except para capturar situações em que elementos não são encontrados.
Prefira localização por imagem a coordenadas fixas: scripts baseados em locateCenterOnScreen() são mais resilientes a mudanças de layout.
Recursos, comunidades e suporte
Para continuar aprendendo e resolver dúvidas, esses são os principais recursos disponíveis:
Documentação oficial: pyautogui.readthedocs.io — a referência completa com todos os métodos e exemplos.
GitHub do projeto: github.com/asweigart/pyautogui — código-fonte aberto, onde você pode reportar bugs e contribuir.
Reddit r/learnpython: uma comunidade ativa onde devs compartilham dúvidas e soluções sobre Python em geral.
Python Discuss: discuss.python.org — fórum da comunidade Python.
Conclusão e próximos passos
O PyAutoGUI é uma das ferramentas mais acessíveis para quem quer começar a automatizar tarefas repetitivas com Python. Ele é fácil de instalar, tem uma API simples e funciona nos principais sistemas operacionais, uma combinação perfeita para devs que querem ganhar produtividade.
Mas a automação é só o começo. Se você quer ir além e dominar o desenvolvimento back-end de verdade, construindo APIs robustas, trabalhando com arquiteturas escaláveis e aplicando as práticas que o mercado exige, vale a pena seguir uma jornada estruturada.
São instrutores que atuam no mercado, desafios reais e conteúdos práticos que conectam o que você aprende com o que as empresas procuram.
Se você já automatiza com PyAutoGUI, imagine o que pode construir dominando back-end de ponta a ponta. Dá uma olhada na carreira e veja como evoluir sua base de Python para o próximo nível profissional.
FAQ | Perguntas frequentes sobre PyAutoGUI
1. O PyAutoGUI funciona em qualquer sistema operacional?
Sim! O PyAutoGUI é compatível com Windows, macOS e Linux. No entanto, a instalação pode exigir dependências diferentes em cada sistema.
No Windows, a instalação básica via pip já é suficiente. No macOS, podem ser necessárias bibliotecas adicionais do pyobjc. No Linux, é preciso instalar dependências como python3-tk e scrot para captura de tela.
2. Posso usar o PyAutoGUI para automatizar navegadores web?
Tecnicamente sim, mas não é a melhor escolha para esse caso. O PyAutoGUI é uma ferramenta de automação de interface gráfica em geral, o que significa que ele "vê" o navegador como qualquer outra janela.
Para automação de navegadores web, ferramentas como Selenium são muito mais adequadas, pois interagem diretamente com o DOM da página, são mais rápidas e mais resistentes a mudanças de layout. O PyAutoGUI brilha quando você precisa automatizar sistemas sem API ou navegadores de forma que outras ferramentas não conseguem.
3. Como evitar que meu script PyAutoGUI fique fora de controle?
O PyAutoGUI possui um mecanismo de segurança chamado Fail-Safe, que é ativado por padrão. Se o cursor do mouse for movido para qualquer canto da tela durante a execução do script, ele lança uma exceção e encerra a automação.
Além disso, é uma boa prática adicionar pausas entre as ações, o que dá tempo para reagir caso algo saia do esperado. Nunca desative o Fail-Safe em scripts que você está desenvolvendo.
4. O PyAutoGUI consegue ler texto da tela?
Não nativamente. O PyAutoGUI não possui funcionalidade de OCR (reconhecimento ótico de caracteres). Para ler texto da tela, você precisa combinar o PyAutoGUI com uma biblioteca de OCR como o pytesseract.
O fluxo típico é: capturar a tela com pyautogui.screenshot(), salvar a imagem e processá-la com pytesseract para extrair o texto.
