PyQGIS para Iniciantes: Automatize Tarefas no QGIS

Chega um ponto em qualquer fluxo de trabalho com QGIS em que repetir a mesma sequência de operações manualmente deixa de ser opção. Reprojetar dezenas de camadas uma a uma, exportar layouts em lote, filtrar feições com os mesmos critérios toda semana. Esse é o momento em que o Python Console do QGIS deixa de ser curiosidade e vira ferramenta de trabalho.

O PyQGIS é a interface de programação que expõe quase toda a funcionalidade do QGIS para scripts Python. Lançado na versão 3.0 do QGIS (2018), ele foi reescrito sobre Python 3 e PyQt5, tornando-se a base para automação, desenvolvimento de plugins e integração com pipelines de dados geoespaciais. A documentação oficial do QGIS Developer Cookbook é o repositório de referência para quem quer avançar além do básico. Este artigo cobre o ponto de entrada: o que é o PyQGIS, como o console funciona e os primeiros scripts que resolvem problemas reais.

O que o PyQGIS consegue fazer que o QGIS manual não consegue com a mesma eficiência

Antes de escrever a primeira linha de código, é importante ter clareza sobre o que justifica o investimento de aprender PyQGIS. A automação no QGIS resolve três categorias distintas de problema:

Tarefas repetitivas em lote: reprojeção de múltiplos arquivos, renomeação de campos em dezenas de camadas, exportação de mapas com configurações padronizadas. O que levaria horas de cliques manuais é resolvido por um script de 20 a 30 linhas;
Lógica condicional complexa: selecionar feições que satisfazem múltiplos critérios simultâneos, calcular campos derivados de expressões encadeadas ou gerar saídas diferentes para grupos distintos de dados. Fazer isso manualmente via interface gráfica é propenso a erro e difícil de reproduzir;
Integração com sistemas externos: consumir APIs, ler planilhas Excel com pandas, conectar ao PostGIS, gerar relatórios em PDF de forma programática. O PyQGIS abre o QGIS para o ecossistema Python completo.

O QGIS 4.0, lançado em março de 2026, manteve total compatibilidade com scripts PyQGIS escritos para a série 3.x, com melhorias no motor de renderização e nas APIs de análise raster. Scripts existentes funcionam na nova versão sem reescrita.

O Python Console: onde o PyQGIS começa

O ponto de entrada mais direto é o Python Console embutido no QGIS, acessível pelo menu Plugins → Python Console ou pelo atalho Ctrl+Alt+P. Ele abre um painel interativo na parte inferior da janela com duas seções: o prompt de linha de comando e o editor de script.

O prompt executa uma linha por vez e é útil para inspeção rápida de objetos, teste de comandos e exploração da API. O editor de script, acessível pelo ícone de bloco de notas no topo do console, aceita scripts com múltiplas linhas e tem botão de execução direta. Para projetos maiores, o editor integrado do QGIS ou um ambiente externo como o VS Code com a extensão PyQGIS configurada são mais eficientes.

O primeiro comando que qualquer tutorial de PyQGIS ensina é este:

iface.activeLayer().name()

Ele retorna o nome da camada ativa na tela. O objeto iface é a instância da interface QGIS disponível automaticamente no console, que dá acesso ao projeto, às camadas, ao canvas e aos painéis. É por ele que a maioria das operações interativas começa.

Os três objetos que sustentam 80% dos scripts PyQGIS

A API do PyQGIS tem centenas de classes e métodos, mas a maior parte dos scripts de automação cotidiana gira em torno de três objetos centrais. Entender o que cada um representa elimina boa parte da confusão inicial.

QgsProject.instance() — o projeto aberto no QGIS. Por aqui você acessa todas as camadas carregadas, as configurações de CRS do projeto, os grupos de camadas e os metadados do arquivo .qgz. Para listar todas as camadas carregadas no projeto atual:

for layer in QgsProject.instance().mapLayers().values():
    print(layer.name())

QgsVectorLayer — representa uma camada vetorial (pontos, linhas ou polígonos). Por ela você acessa feições, filtra por atributos, edita geometria, calcula campos e exporta dados. Para acessar a camada ativa e iterar sobre suas feições:

layer = iface.activeLayer()
for feature in layer.getFeatures():
    print(feature['nome_do_campo'])

processing.run() — executa qualquer algoritmo disponível no Processador do QGIS de forma programática. Isso inclui os algoritmos nativos do QGIS, do GDAL, do GRASS e os de qualquer plugin instalado. A chamada abaixo, por exemplo, reprojeta uma camada para SIRGAS 2000 (EPSG:4674):

processing.run("native:reprojectlayer", {
    'INPUT': layer,
    'TARGET_CRS': QgsCoordinateReferenceSystem('EPSG:4674'),
    'OUTPUT': '/caminho/para/saida.gpkg'
})

O processing.run() é o atalho mais poderoso para iniciantes porque elimina a necessidade de entender toda a API de baixo nível. Se um algoritmo existe no Processador do QGIS, ele pode ser chamado via script com os mesmos parâmetros da interface gráfica.

Caderno com anotações de script Python para automação de tarefas de geoprocessamento no QGIS — Mapear o fluxo no papel antes de codificar reduz o tempo de depuração do script PyQGIS em projetos mais complexos

Script prático: reprojetar todas as camadas do projeto de uma vez

Este é um caso de uso real e recorrente: receber um conjunto de shapefiles em projeções diferentes e padronizá-los em SIRGAS 2000. O script abaixo itera sobre todas as camadas vetoriais do projeto, reprojeta cada uma e salva como GeoPackage em uma pasta de saída:

import os
from qgis.core import QgsProject, QgsCoordinateReferenceSystem
import processing

pasta_saida = '/home/usuario/dados_reprojetados/'
crs_destino = QgsCoordinateReferenceSystem('EPSG:4674')

for layer in QgsProject.instance().mapLayers().values():
    if layer.type() == layer.VectorLayer:
        nome_arquivo = os.path.join(pasta_saida, layer.name() + '.gpkg')
        processing.run("native:reprojectlayer", {
            'INPUT': layer,
            'TARGET_CRS': crs_destino,
            'OUTPUT': nome_arquivo
        })
        print(f"Exportada: {layer.name()}")

Ajuste pasta_saida para o diretório de trabalho do seu projeto. O script não altera as camadas originais: cria novos arquivos na pasta de destino. Para cada camada processada, imprime uma confirmação no console.

Script prático: calcular área em hectares e adicionar como campo

Outro uso frequente: adicionar um campo calculado a uma camada de polígonos sem passar pela calculadora de campo da interface gráfica. O script abaixo abre a camada em modo de edição, cria o campo area_ha e calcula a área em hectares para cada feição:

from qgis.core import QgsField, QgsProject
from PyQt5.QtCore import QVariant

layer = iface.activeLayer()
layer.startEditing()

# Adiciona o campo se ainda não existir
if 'area_ha' not in [field.name() for field in layer.fields()]:
    layer.addAttribute(QgsField('area_ha', QVariant.Double))
    layer.updateFields()

idx = layer.fields().indexFromName('area_ha')

for feature in layer.getFeatures():
    area = feature.geometry().area() / 10000  # m² para hectares
    layer.changeAttributeValue(feature.id(), idx, round(area, 4))

layer.commitChanges()
print("Campo area_ha calculado com sucesso.")

Este script assume que a camada já está em um sistema de referência projetado em metros (como SIRGAS 2000 / UTM). Camadas em graus decimais retornam valores incorretos de área sem reprojeção prévia.

Como descobrir os parâmetros de qualquer algoritmo sem consultar a documentação

Um dos maiores obstáculos para quem está começando com PyQGIS é descobrir quais parâmetros passar para processing.run(). A resposta mais rápida não está na documentação: está dentro do próprio QGIS.

Execute qualquer algoritmo normalmente pela interface gráfica do Processador. Ao final da execução, o painel de resultados exibe um botão “Ver log”. Nele, há uma linha chamada “Equivalent Python expression” com a chamada exata de processing.run() que replicaria aquela operação, incluindo todos os parâmetros com os valores que você usou. Basta copiar, ajustar as variáveis e já tem um script funcional.

Essa técnica elimina o ciclo de tentativa e erro na construção de chamadas de processamento e acelera consideravelmente a curva de aprendizado de PyQGIS na prática.

O próximo passo depois dos primeiros scripts

Dominar o console e os scripts básicos é a Fase 1. A progressão natural passa por três frentes:

Scripts standalone (fora do QGIS): com o módulo qgis.core importado via Python externo, é possível rodar análises geoespaciais em servidores, pipelines de CI/CD ou tarefas agendadas sem abrir a interface gráfica;
Desenvolvimento de plugins: a estrutura de um plugin PyQGIS é basicamente um script Python com um arquivo de metadados. O Plugin Builder, disponível no repositório oficial do QGIS, gera o esqueleto de código para que você se concentre na lógica de negócio;
Integração com GeoPandas e Shapely: combinar o PyQGIS com o ecossistema científico do Python abre análises que as ferramentas nativas do QGIS não cobrem nativamente, especialmente em processamento estatístico e visualizações customizadas.

Para quem quer construir esse caminho com estrutura e conteúdo em português voltado ao contexto brasileiro, a comunidade do qgis.com.br reúne tutoriais, materiais e discussões técnicas sobre QGIS e PyQGIS aplicados às demandas reais do geoprocessamento no Brasil.

Perguntas Frequentes

Preciso saber Python antes de começar com PyQGIS?

Conhecimento básico de Python ajuda, mas não é obrigatório para começar. Os primeiros scripts de automação seguem estruturas simples de loop e chamada de função que qualquer introdução ao Python em um dia de estudo já cobre. O aprendizado simultâneo de Python e PyQGIS é viável partindo de exemplos práticos.

O PyQGIS funciona no QGIS 4.0?

Sim. O QGIS 4.0, lançado em março de 2026, manteve compatibilidade com a API PyQGIS da série 3.x. Scripts escritos para QGIS 3.x funcionam na nova versão sem reescrita obrigatória, com exceção de recursos que usavam APIs marcadas como depreciadas nas versões finais da série 3.

Qual a diferença entre usar o Python Console do QGIS e um script externo com qgis.core?

O Console executa dentro do ambiente QGIS com acesso ao projeto aberto e ao objeto iface. Um script externo precisa inicializar o QGIS manualmente via QgsApplication, mas permite rodar análises sem abrir a interface gráfica, ideal para automações em servidor, agendamentos e pipelines de dados em produção.