Installation

pip

The simplest way to install PySUS is via pip:

pip install pysus

For the local web interface:

pip install pysus[web]

A pre-built JupyterLab image is available on Docker Hub:

docker pull alertadengue/pysus
docker run -p 8888:8888 alertadengue/pysus

Or build locally and start the container:

docker compose up --build

Then open the JupyterLab interface at port 8888 in your browser.

Stop the container with:

docker compose down

Using Conda:

conda env create -f conda/dev.yaml
conda activate pysus

Using Poetry:

poetry install

PySUS includes a local Streamlit-based web server for browsing and downloading datasets interactively. Start it with:

pysus web

Or directly:

streamlit run pysus/web/app.py

This opens a browser at http://localhost:8501 with a graphical interface for querying PySUS s3, DATASUS FTP, and dados.gov.br sources.

Variable	Purpose
`PYSUS_CACHEPATH`	Directory for cached files and local catalogs (default `~/pysus`)
`DADOSGOV_TOKEN`	API token for the dados.gov.br client (required for DadosGov downloads)
`ACCESS_KEY`	S3 access key for writing to the PySUS bucket (catalog maintenance)
`SECRET_KEY`	S3 secret key for writing to the PySUS bucket (catalog maintenance)

By default, downloaded files are cached in ~/pysus. Override this with the PYSUS_CACHEPATH environment variable:

import os
os.environ["PYSUS_CACHEPATH"] = "/my/custom/path"