Instalação do QGIS e QSWAT+ no Linux Mint

Ambiente testado: Linux Mint 22 · QGIS 3.44 · Python 3.12 · QSWAT+ 3.2.1
Arquitetura: x86_64 (64 bits)

Sumário

Instalação do QGIS via repositório oficial
1.5 Instalar uma versão específica (incluindo downgrade)
Instalação do SWAT+ Editor
Instalação do plugin QSWAT+
Compilação dos módulos Cython
Compilação e instalação do TauDEM
Configuração dos bancos de dados
Ativação e configuração no QGIS
Fluxo básico de uso
Solução de problemas

1. Instalação do QGIS via repositório oficial

⚠️ Não use o pacote do repositório padrão do Ubuntu/Mint — ele costuma estar desatualizado. Use o repositório oficial do QGIS para sempre ter a versão mais recente.

1.1. Adicionar a chave GPG do repositório

sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/qgis-archive-keyring.gpg \
  https://download.qgis.org/downloads/qgis-archive-keyring.gpg

1.2. Adicionar o repositório QGIS

Identifique o codinome da sua base Ubuntu com lsb_release -cs (ex: noble para Mint 22, jammy para Mint 21) e ajuste abaixo:

sudo tee /etc/apt/sources.list.d/qgis.sources << EOF
Types: deb deb-src
URIs: https://qgis.org/debian
Suites: noble
Architectures: amd64
Components: main
Signed-By: /etc/apt/keyrings/qgis-archive-keyring.gpg
EOF

Para versão LTR (Long Term Release), substitua https://qgis.org/debian por https://qgis.org/debian-ltr.

1.3. Instalar o QGIS

sudo apt update
sudo apt install qgis qgis-plugin-grass

1.4. Verificar a instalação

qgis --version

1.5. Instalar uma versão específica (incluindo downgrade)

O procedimento padrão acima instala sempre a versão mais recente disponível. Se você precisar de uma versão específica — por exemplo, a 3.40 (LTR) para compatibilidade com plugins como o QSWAT+ — siga os passos abaixo.

Pré-requisito: adicionar os dois repositórios

Para ter acesso ao histórico completo de versões, adicione ambos os repositórios: o LTR e o geral. Substitua noble pelo seu codename caso necessário.

# Repositório LTR (versões 3.28, 3.34, 3.40...)
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/qgis-archive-keyring.gpg] \
https://qgis.org/ubuntu-ltr noble main" \
| sudo tee /etc/apt/sources.list.d/qgis-ltr.list

# Repositório geral (todas as versões)
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/qgis-archive-keyring.gpg] \
https://qgis.org/debian noble main" \
| sudo tee /etc/apt/sources.list.d/qgis-debian.list

sudo apt update

Verificar versões disponíveis

apt-cache policy qgis

A saída lista todas as versões disponíveis. As versões têm o formato 1:X.Y.Z+40noble. Identifique a versão desejada antes de prosseguir.

Instalar a versão desejada

Substitua X.Y.Z pela versão desejada (ex: 3.40.15):

sudo apt install --allow-downgrades \
  qgis=1:X.Y.Z+40noble \
  qgis-common=1:X.Y.Z+40noble \
  qgis-providers=1:X.Y.Z+40noble \
  qgis-providers-common=1:X.Y.Z+40noble \
  qgis-plugin-grass=1:X.Y.Z+40noble \
  qgis-plugin-grass-common=1:X.Y.Z+40noble \
  qgis-provider-grass=1:X.Y.Z+40noble \
  python3-qgis=1:X.Y.Z+40noble \
  python3-qgis-common=1:X.Y.Z+40noble

Atenção: é obrigatório especificar todos os pacotes dependentes com a mesma versão. O apt não resolve downgrade de dependências automaticamente — omitir qualquer pacote resulta em erro de dependências desencontradas.

Verificar

qgis --version

Fixar a versão (impedir atualizações automáticas)

Após instalar a versão desejada, marque os pacotes como hold para que apt upgrade não os atualize acidentalmente:

sudo apt-mark hold \
  qgis qgis-common qgis-providers qgis-providers-common \
  qgis-plugin-grass qgis-plugin-grass-common qgis-provider-grass \
  python3-qgis python3-qgis-common

Para confirmar quais pacotes estão fixados:

apt-mark showhold

Remover o hold (quando quiser atualizar no futuro)

sudo apt-mark unhold \
  qgis qgis-common qgis-providers qgis-providers-common \
  qgis-plugin-grass qgis-plugin-grass-common qgis-provider-grass \
  python3-qgis python3-qgis-common

sudo apt upgrade

2. Instalação do SWAT+ Editor

O SWAT+ Editor é o componente que edita os inputs do modelo SWAT+ e é exigido pelo QSWAT+.

2.1. Baixar o pacote Linux

Baixe o arquivo .tar.gz diretamente do GitHub Releases:

cd ~/Downloads
wget https://github.com/swat-model/swatplus-editor/releases/download/v3.2.1/swatplus-editor-3.2.1-linux-x64.tar.gz

Ou acesse manualmente: https://github.com/swat-model/swatplus-editor/releases

2.2. Descompactar

cd ~/Downloads
tar -xzf swatplus-editor-3.2.1-linux-x64.tar.gz
cd swatplus-editor-3.2.1-linux-x64   # ou o nome da pasta extraída

2.3. Mover para um local permanente

mkdir -p ~/.local/share/SWATPlusEditor
cp -r * ~/.local/share/SWATPlusEditor/

2.4. Dar permissão de execução

chmod +x ~/.local/share/SWATPlusEditor/SWATPlusEditor
chmod +x ~/.local/share/SWATPlusEditor/SWATPlusEditor.bin

2.5. Testar

~/.local/share/SWATPlusEditor/SWATPlusEditor

A interface gráfica do editor deve abrir. Se abrir sem erros, a instalação está correta.

3. Instalação do plugin QSWAT+

⚠️ O QSWAT+ não está disponível no repositório oficial de plugins do QGIS. A instalação é feita manualmente via source code.

3.1. Instalar dependências do sistema

sudo apt install python3-pandas python3-numpy python3-matplotlib \
                 python3-dev cython3 build-essential python3-numpy

3.2. Baixar o source code do QSWAT+

Acesse: https://github.com/swat-model/QSWATPlus/releases

Baixe o Source code (zip) da versão mais recente (ex: QSWATPlus-3.2.1.zip) e extraia:

cd ~/Downloads
unzip QSWATPlus-3.2.1.zip

3.3. Criar a estrutura correta de pastas do plugin

O QGIS espera uma estrutura específica:

~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/
  QSWATPlus/              ← pasta raiz do plugin
    __init__.py
    metadata.txt
    QSWATPlus/            ← subpasta com o código-fonte
      QSWATPlusMain.py
      DBUtils.py
      ... (demais arquivos)

Execute os comandos abaixo para montar essa estrutura:

PLUGIN_DIR=~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus

# Cria as pastas
mkdir -p "$PLUGIN_DIR/QSWATPlus"

# Copia todo o conteúdo do source para a subpasta
cp -r ~/Downloads/QSWATPlus-3.2.1/QSWATPlus/* "$PLUGIN_DIR/QSWATPlus/"

# Copia os arquivos que o QGIS exige na RAIZ do plugin
cp "$PLUGIN_DIR/QSWATPlus/__init__.py" "$PLUGIN_DIR/__init__.py"

3.4. Criar o metadata.txt para Linux 64-bit

O repositório inclui vários arquivos de metadata por plataforma. No Linux 64-bit, o metadata.txt deve estar na raiz da pasta do plugin (não dentro da subpasta):

cp "$PLUGIN_DIR/QSWATPlus/metadatalinux3_64.txt" \
   "$PLUGIN_DIR/metadata.txt"

Confirme o conteúdo:

cat "$PLUGIN_DIR/metadata.txt"

Saída esperada:

[general]
name=QSWATPlusLinux3_64
qgisMinimumVersion=3.16
description=Create SWAT+ inputs
version=2.5.5
author=Chris George
email=cgeorge@tamu.edu

4. Compilação dos módulos Cython

O QSWAT+ depende de módulos escritos em Cython (.pyx) que precisam ser compilados para a versão do Python em uso. Os binários pré-compilados no repositório são para Python 3.6 e não funcionam com Python 3.12.

4.1. Compilar os arquivos `.pyx` para `.c`

cd "$PLUGIN_DIR/QSWATPlus"

cython3 dataInC.pyx
cython3 polygonizeInC.pyx
cython3 polygonizeInC2.pyx
cython3 jenks.pyx

4.2. Compilar os `.c` para `.so`

python3 -c "
import sysconfig, subprocess, numpy

inc      = sysconfig.get_path('include')
numpyinc = numpy.get_include()
ext      = sysconfig.get_config_var('EXT_SUFFIX')

# dataInC não precisa de numpy
ret = subprocess.run([
    'gcc', '-shared', '-fPIC', '-O2',
    'dataInC.c', '-o', f'dataInC{ext}',
    f'-I{inc}'
], capture_output=True, text=True)
print('Compilado: dataInC' if ret.returncode == 0 else f'ERRO dataInC:\n{ret.stderr}')

# Os demais precisam do include do numpy
for name in ['polygonizeInC', 'polygonizeInC2', 'jenks']:
    ret = subprocess.run([
        'gcc', '-shared', '-fPIC', '-O2',
        f'{name}.c', '-o', f'{name}{ext}',
        f'-I{inc}', f'-I{numpyinc}'
    ], capture_output=True, text=True)
    if ret.returncode == 0:
        print(f'Compilado: {name}{ext}')
    else:
        print(f'ERRO em {name}:\n{ret.stderr}')
"

Saída esperada:

Compilado: dataInC
Compilado: polygonizeInC.cpython-312-x86_64-linux-gnu.so
Compilado: polygonizeInC2.cpython-312-x86_64-linux-gnu.so
Compilado: jenks.cpython-312-x86_64-linux-gnu.so

5. Compilação e instalação do TauDEM

⚠️ O pacote taudem do repositório apt não funciona corretamente com o QSWAT+ 3.2.1 no Linux Mint 22. É necessário compilar o TauDEM a partir do código-fonte e instalar os binários no diretório correto do plugin.

5.1. Instalar dependências de compilação

sudo apt install -y cmake libgdal-dev gdal-bin libopenmpi-dev openmpi-bin

Verifique se o MPI está disponível:

which mpiexec   # deve retornar /usr/bin/mpiexec

5.2. Clonar o repositório do TauDEM

cd ~/Downloads
git clone https://github.com/dtarb/TauDEM.git

5.3. Compilar

cd TauDEM/src
mkdir build && cd build
cmake ..
make -j$(nproc)

O flag -j$(nproc) usa todos os núcleos disponíveis para paralelizar a compilação.

Ao final, a pasta build deve conter os binários, incluindo: pitremove, d8flowdir, aread8, streamnet, threshold, entre outros.

5.4. Criar o diretório de destino

O QSWAT+ 3.2.1 procura os binários do TauDEM em dois locais possíveis (na ordem):

~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/TauDEM5Bin
/usr/local/share/SWATPlus/TauDEM5Bin

⚠️ Atenção: O diretório correto é plugins/QSWATPlus/TauDEM5Bin (raiz do plugin), não plugins/QSWATPlus/QSWATPlus/SWATPlus/TauDEM5Bin (subpasta). Instalar no caminho errado não resolve o erro.

Crie o diretório correto:

mkdir -p ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/TauDEM5Bin

5.5. Copiar os binários

TAUDEM_SRC=~/Downloads/TauDEM/src/build
TAUDEM_DEST=~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/TauDEM5Bin

cp "$TAUDEM_SRC/aread8" \
   "$TAUDEM_SRC/areadinf" \
   "$TAUDEM_SRC/pitremove" \
   "$TAUDEM_SRC/d8flowdir" \
   "$TAUDEM_SRC/dinfflowdir" \
   "$TAUDEM_SRC/streamnet" \
   "$TAUDEM_SRC/threshold" \
   "$TAUDEM_SRC/moveoutletstostreams" \
   "$TAUDEM_SRC/dropanalysis" \
   "$TAUDEM_SRC/gridnet" \
   "$TAUDEM_SRC/catchhydrogeo" \
   "$TAUDEM_SRC/d8hdisttostrm" \
   "$TAUDEM_DEST/"

5.6. Verificar

ls ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/TauDEM5Bin/

Deve listar os binários copiados.

6. Configuração dos bancos de dados

⚠️ O QSWAT+ 3.2.1 no Linux requer que os arquivos de banco de dados SQLite estejam em um diretório específico na raiz do plugin, separado da subpasta de código. Eles não são copiados automaticamente durante a instalação.

6.1. Criar o diretório de bancos de dados

mkdir -p ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/Databases

6.2. Copiar os arquivos de banco de dados

Os arquivos estão na pasta Databases do source code baixado:

cp ~/Downloads/QSWATPlus-3.2.1/Databases/* \
   ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/Databases/

Isso copia: QSWATPlusProj.sqlite, QSWATPlusProjHAWQS.sqlite, QSWATPlusRefHAWQS.sqlite, gwflow.ini e example.qgs.

6.3. Criar link simbólico para o banco de referência

O QSWAT+ procura por swatplus_datasets.sqlite, mas o arquivo incluído no pacote se chama QSWATPlusRefHAWQS.sqlite. Crie um link simbólico:

ln -s \
  ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/Databases/QSWATPlusRefHAWQS.sqlite \
  ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/Databases/swatplus_datasets.sqlite

6.4. Verificar

ls -la ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/Databases/

A saída deve mostrar os arquivos copiados e o link simbólico apontando para QSWATPlusRefHAWQS.sqlite:

-rw-rw-r-- 1 usuario usuario  2116608 QSWATPlusProj.sqlite
-rw-rw-r-- 1 usuario usuario 18835456 QSWATPlusProjHAWQS.sqlite
-rw-rw-r-- 1 usuario usuario  1417216 QSWATPlusRefHAWQS.sqlite
lrwxrwxrwx 1 usuario usuario      115 swatplus_datasets.sqlite -> .../QSWATPlusRefHAWQS.sqlite

7. Ativação e configuração no QGIS

7.1. Habilitar plugins experimentais

No QGIS: Complementos → Gerenciar e Instalar Complementos → Opções

Marque: - ☑ Mostrar também complementos experimentais - ☑ Mostrar também complementos obsoletos

Clique em Recarregar todos os repositórios.

7.2. Ativar o QSWAT+

Vá em Complementos → Gerenciar e Instalar Complementos → Instalados

Marque o checkbox ao lado de QSWATPlusLinux3_64.

7.3. Verificar o carregamento

Se o plugin não aparecer no menu Complementos após ativação, verifique erros em:

Exibir → Painéis → Log de Mensagens → aba Python

7.4. Corrigir o locale para separador decimal

⚠️ O QSWAT+ 3.2.1 tem um bug com locale pt_BR: os campos numéricos usam vírgula como separador decimal, mas o código Python espera ponto. Isso causa erro ValueError: could not convert string to float: '1,0' ao salvar os parâmetros.

Solução: forçar o QGIS a usar locale en_US:

Menu Configurações → Opções → Geral
Marque ☑ "Substituir locale do sistema" (Override system locale)
Selecione English United States (en_US)
Clique em OK
Feche e reabra o QGIS completamente

7.5. Configurar o QSWAT+ Parameters

Na primeira execução do QSWAT+ (Complementos → QSWAT+ → QSWAT+), clique em QSWAT+ Parameters e configure:

Campo	Valor
SWATPlus directory	`/home/<usuario>/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/QSWATPlus/SWATPlus`
MPI bin directory	`/usr/bin`

Para localizar o SWATPlus directory correto no seu sistema:

find ~/.local /usr /opt -name "SWATPlus" -type d 2>/dev/null

Após preencher, clique em Save. Os campos de multiplicadores devem estar com ponto decimal (ex: 1.0) após a correção do locale.

8. Fluxo básico de uso

Após ativar e configurar o plugin, acesse pelo menu Complementos → QSWAT+.

A sequência típica de um projeto é:

New Project — define nome e pasta do projeto
Delineate Watershed — carrega o DEM e delimita a bacia hidrográfica usando TauDEM
Create HRUs — define camadas de uso do solo, tipo de solo e declividade
Edit Inputs — abre o SWAT+ Editor para ajustar parâmetros do modelo
Run SWAT+ — executa o modelo e gera as saídas

9. Solução de problemas

Plugin não aparece na busca do gerenciador

O QSWAT+ não está no repositório oficial. A instalação é exclusivamente via source code conforme descrito na seção 3.

`ModuleNotFoundError: No module named 'QSWATPlus.QSWATPlus'`

A subpasta do código-fonte não foi criada corretamente. Verifique se a estrutura está assim:

plugins/QSWATPlus/QSWATPlus/QSWATPlusMain.py

Se não estiver, refaça o passo 3.3.

`Falta init.py`

O __init__.py deve estar na raiz da pasta do plugin. Execute:

PLUGIN_DIR=~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus
cp "$PLUGIN_DIR/QSWATPlus/__init__.py" "$PLUGIN_DIR/__init__.py"

`Arquivo de metadados faltando`

O metadata.txt deve estar na raiz da pasta do plugin, não dentro da subpasta. Execute:

PLUGIN_DIR=~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus
cp "$PLUGIN_DIR/QSWATPlus/metadatalinux3_64.txt" "$PLUGIN_DIR/metadata.txt"

`ModuleNotFoundError: No module named 'QSWATPlus.QSWATPlus.dataInC'`

Os módulos Cython precisam ser compilados. Execute todo o passo 4.

`fatal error: numpy/arrayobject.h: Arquivo ou diretório inexistente`

Instale o pacote de desenvolvimento do numpy:

sudo apt install python3-numpy

Em seguida, recompile passando o include do numpy com -I$(python3 -c "import numpy; print(numpy.get_include())").

`Cannot find SWATPlus directory`

O QSWAT+ não encontrou a pasta SWATPlus. Abra QSWAT+ Parameters e aponte o campo SWATPlus directory para o caminho correto encontrado com:

find ~/.local -name "SWATPlus" -type d 2>/dev/null

`Cannot find TauDEM directory`

O QSWAT+ procura os binários do TauDEM em plugins/QSWATPlus/TauDEM5Bin. Verifique se o diretório existe e contém os binários:

ls ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/QSWATPlus/TauDEM5Bin/

Se estiver vazio ou não existir, refaça a seção 5 completa.

⚠️ O pacote sudo apt install taudem não resolve este problema — o QSWAT+ não encontra os binários instalados via apt porque espera um diretório específico dentro da estrutura do plugin. É obrigatório compilar e copiar conforme a seção 5.

`ValueError: could not convert string to float: '1,0'`

Bug de locale. O sistema está usando vírgula como separador decimal, mas o código Python espera ponto. Siga o passo 6.4 para forçar o locale en_US no QGIS.

`Cannot find project database template` / `sqlite3.OperationalError: no such table`

Os arquivos SQLite de template não estão no diretório correto. O QSWAT+ procura em plugins/QSWATPlus/Databases/, mas eles estão na subpasta do source. Execute toda a seção 6 para copiar os arquivos e criar o link simbólico necessário.

⚠️ O arquivo swatplus_datasets.sqlite não existe no pacote do QSWAT+ 3.2.1 — o arquivo equivalente é QSWATPlusRefHAWQS.sqlite. O link simbólico do passo 6.3 resolve isso sem necessidade de renomear o arquivo original.

Erro de instalação de pacotes pip (`externally-managed-environment`)

No Linux Mint, prefira instalar pacotes Python via apt:

sudo apt install python3-pandas python3-numpy python3-matplotlib

Se precisar usar pip para um pacote não disponível no apt:

pip3 install --user <pacote> --break-system-packages

Documentação gerada em abril de 2026 com base em instalação real no Linux Mint 22 com QGIS 3.44.7-Solothurn e QSWAT+ 3.2.1.