PyQGIS: o que é e como automatizar o QGIS com Python
Publicado em
PyQGIS é a forma de controlar o QGIS com código Python. Tudo o que você faz com cliques no QGIS também pode virar poucas linhas de Python: carregar uma camada, rodar uma ferramenta, mudar um estilo, exportar um mapa. Assim você repete a mesma tarefa em cem arquivos sem clicar cem vezes. O PyQGIS já vem em toda instalação do QGIS, então não há nada para adicionar.
O PyQGIS Developer Cookbook diz que as ferramentas Python são “praticamente idênticas” às usadas para construir o próprio QGIS, então quase tudo é possível. A maioria dos plugins do QGIS, incluindo os nossos, é escrita com ele.
Você não precisa mais escrever o código sozinho. Um chatbot pode redigir o script, e um agente pode dispensar o código por completo: nós desenvolvemos um, o AI Agent, e mais adiante eu testo os dois nas mesmas seis tarefas.
Onde rodar o PyQGIS
São quatro lugares, e cada um serve a um tipo de tarefa.
| Onde | Como abrir | Para que serve |
|---|---|---|
| Terminal Python | Complementos > Terminal Python (Ctrl+Alt+P) | Ajustes rápidos no projeto que você tem aberto |
| Script de processamento | Caixa de Ferramentas de Processamento > Scripts > Criar novo Script a partir do modelo | Uma ferramenta reutilizável, com entradas próprias, como qualquer outra da caixa de ferramentas |
| Plugin | Uma pasta no seu perfil do QGIS | Uma ferramenta com botões próprios, para compartilhar com outras pessoas |
| Script independente | Python puro ou o comando qgis_process | Tarefas que rodam sem janela do QGIS, como em um servidor |
O terminal oferece o iface, o objeto que controla a janela do QGIS. Fora do QGIS ele não existe, e é por isso que NameError: name 'iface' is not defined é uma das perguntas mais frequentes sobre PyQGIS no GIS Stack Exchange.
Um script de processamento começa de um modelo que o QGIS preenche para você. Você troca as entradas e as poucas linhas que fazem o trabalho, e o script aparece na caixa de ferramentas como uma ferramenta nativa.
Seu primeiro script PyQGIS
Abra o Terminal Python, clique em Mostrar editor, selecione uma camada de edificações no painel Camadas e cole o código abaixo. Ele conta as edificações de cada tipo:
from collections import Counter
layer = iface.activeLayer() # the layer selected in the Layers panel
counts = Counter(f["building"] for f in layer.getFeatures())
for kind, n in counts.most_common(5):
print(kind, n)
print("Total:", layer.featureCount(), "features in", layer.crs().authid())
Três objetos fazem a maior parte do trabalho: QgsProject.instance() é o seu projeto, QgsVectorLayer e QgsRasterLayer são as camadas dele, e iface é a janela. A referência da API lista todas as classes.
Rode qualquer ferramenta do QGIS com Python
Toda ferramenta da Caixa de Ferramentas de Processamento pode rodar com uma linha de Python, processing.run(), com os mesmos parâmetros da janela dela:
import processing
result = processing.run("native:buffer", {
"INPUT": "buildings.gpkg",
"DISTANCE": 50,
"OUTPUT": "buffered.gpkg",
})
Você não precisa adivinhar o nome dos parâmetros. Preencha a janela da ferramenta uma vez e abra Avançado > Copiar como comando Python, na parte de baixo. O QGIS entrega a linha exata para colar no seu script.
As mesmas ferramentas rodam sem abrir o QGIS, direto do terminal do sistema, com qgis_process run native:buffer. É o caminho para uma tarefa agendada em um servidor.
O que o QGIS 4 mudou para o PyQGIS
O QGIS 4.0, lançado em 6 de março de 2026, passou a usar uma versão mais nova do Qt, o conjunto de ferramentas por trás das janelas e botões. As funções do QGIS ficaram quase iguais. O que quebra é o código que usa o Qt diretamente, e três mudanças causam a maior parte dos problemas:
| QGIS 3 | QGIS 4 |
|---|---|
Nomes curtos, como Qt.AlignLeft | Nomes completos, como Qt.AlignmentFlag.AlignLeft |
QRegExp | QRegularExpression |
exec_() em caixas de diálogo | exec() |
O QGIS inclui um script, o pyqt5_to_pyqt6.py, que reescreve a maioria desses trechos para você, e o pyqgis4-checker encontra o resto. Scripts que usam apenas ferramentas do QGIS e processing.run() costumam funcionar sem alterações.
O ChatGPT ou o Claude conseguem escrever PyQGIS para você?
Na maioria das vezes sim, se você explicar o seu projeto. Testei o Claude Sonnet, um chatbot como o ChatGPT, e os scripts dele rodaram sem erro nas seis tarefas. Quando descrevi as camadas, os campos e os caminhos dos arquivos, os seis resultados estavam certos. Quando passei apenas os nomes das camadas, um dos seis saiu errado em silêncio: o script rodou, não mostrou nenhum alerta e preencheu 396 de 936 pixels de um mapa de elevação com uma altura falsa de 0 m.
| Rodou sem erro | Resultado correto | |
|---|---|---|
| Chatbot, projeto descrito no prompt | 6 de 6 | 6 de 6 |
| Chatbot, apenas nomes das camadas | 6 de 6 | 5 de 6 |
| Agente de IA dentro do QGIS, só a frase da tarefa | 6 de 6 | 6 de 6 |
A lição é simples. Um chatbot não enxerga o seu projeto, então a qualidade do código depende de quão bem você o descreve, e um resultado errado pode ter exatamente a mesma aparência de um certo. Houve também uma pegadinha do QGIS 4: os dois scripts de layout de impressão do chatbot usavam os nomes curtos do Qt da tabela acima e parariam no meio do caminho no QGIS 4.
Como medimos. Em 26 de setembro de 2026, no QGIS 3.44.7, com dados do mapa do centro de Denpasar, em Bali: seis tarefas do dia a dia, de contar edificações a exportar um layout de impressão, com uma tentativa cada. Um resultado só contava como correto se um script de verificação separado, escrito antes das execuções, passasse. Seis tarefas é uma amostra pequena.
Ou dispense o código: um agente que executa as etapas
Nós desenvolvemos o AI Agent, então esta seção fala do nosso próprio plugin. É um painel de chat dentro do QGIS: você digita a tarefa, e ele lê o seu projeto, roda as ferramentas e confere o resultado. Não há código para colar nem projeto para descrever.
Dei a ele as mesmas seis frases de tarefa, sem descrever o projeto. Ele acertou as seis, levando entre 6,4 e 42,8 segundos por tarefa e 148,8 segundos no total. Ele parou duas vezes para pedir permissão antes de gravar um arquivo, e eu cliquei em Permitir. Na tarefa de elevação em que o chatbot errou, ele leu a camada primeiro e tratou os pixels vazios corretamente.
O caminho gratuito continua sendo bom: o terminal, o Copiar como comando Python e um chatbot levam você longe, desde que você confira o resultado. Se prefere descrever a tarefa e receber a camada pronta, o agente faz as etapas por você.
Teste o AI Agent grátis no QGIS, sem cartão
Onde as pessoas travam
Contamos as perguntas nos comentários de tutoriais de QGIS no YouTube: em 1.692 tutoriais com comentários, 391 comentários em 245 tutoriais pedem ajuda com Python ou automação. Os mesmos três problemas se repetem:
- Camada não encontrada.
mapLayersByName("roads")não acha nada se o nome diferir por uma letra ou um espaço. - Distâncias em graus. Um buffer de 50 m em uma camada em
EPSG:4326vira um buffer de 50 graus, porque esse sistema conta em graus. Reprojete antes, como explicamos em o que é um SRC. ifacefora do QGIS. Scripts executados fora da janela não têmiface. UseQgsProjecteprocessing.run().
O que lembrar
O PyQGIS é a interface Python do QGIS. Ele roda no Terminal Python, em scripts de processamento, em plugins e fora do QGIS com o qgis_process.
O processing.run() executa qualquer ferramenta do QGIS a partir do código, e Copiar como comando Python entrega a linha exata a partir da janela da ferramenta.
O QGIS 4 renomeou alguns nomes do Qt, como Qt.AlignLeft. Código que cria as próprias janelas pode precisar de pequenos ajustes.
No nosso teste de seis tarefas, o código do chatbot sempre rodou, mas saiu errado uma vez quando o projeto não foi descrito. Um agente dentro do QGIS, como o AI Agent, acertou as seis só com a frase da tarefa.
Perguntas frequentes
Para que serve o PyQGIS?
Para automatizar o QGIS com Python: carregar e editar camadas, rodar ferramentas em vários arquivos, estilizar mapas, montar layouts de impressão e escrever plugins ou scripts que outras pessoas possam reutilizar. Ele também roda fora da janela do QGIS, para tarefas em um servidor.
PyQGIS e Python são a mesma coisa?
O PyQGIS é um conjunto de ferramentas do QGIS que você usa a partir do Python. Você escreve Python normal, e o PyQGIS acrescenta itens como QgsVectorLayer e processing.run(). Ele vem com o QGIS e usa o Python que o QGIS instala.
Como abrir o Terminal Python no QGIS?
Em Complementos > Terminal Python, ou com Ctrl+Alt+P. Clique em Mostrar editor para escrever scripts mais longos, salvá-los como arquivos .py e executá-los com a seta verde.
Meus scripts PyQGIS ainda funcionam no QGIS 4?
Scripts que usam apenas ferramentas do QGIS e processing.run() costumam funcionar. Scripts que criam as próprias janelas muitas vezes precisam de pequenas mudanças, como Qt.AlignmentFlag.AlignLeft no lugar de Qt.AlignLeft. O script oficial pyqt5_to_pyqt6.py corrige a maioria delas.
Dá para automatizar o QGIS sem Python?
Dá. O Modelador Gráfico encadeia ferramentas de forma visual, e o processamento em lote roda uma ferramenta em vários arquivos. Um plugin de agente de IA vai além: você digita a tarefa em linguagem comum e ele executa as ferramentas no seu projeto. O nosso, o AI Agent, tem um plano Free.
Para ir além, o que é um agente de IA no QGIS explica como os agentes funcionam e como escolher um, e o AI Agent é o nosso, para testar grátis. O que é um SRC trata da reprojeção de que a maioria dos scripts precisa logo no início, e o que é o QGIS MCP mostra o caminho para quem usa Claude Code e Cursor.
