Installation

pip

The simplest way to install PySUS is via pip:

pip install pysus

For the terminal user interface (TUI):

pip install pysus[tui]

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 http://127.0.0.1:8888/lab 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.

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"