Installation

ViralUnity is a Python package that launches Snakemake workflows. The tool dependencies are documented in the conda environment file environment.yml and the workflow-specific dependencies are in viralunity/scripts/envs/.

Install from PyPI (recommended)

The ViralUnity CLI is published on PyPI, so the quickest install is:

pip install viralunity

Note

conda (or mamba/micromamba) is still required at runtime. ViralUnity orchestrates Snakemake, which builds the per-rule tool environments (aligners, classifiers, assemblers) via --use-conda on first run — so conda/mamba must be installed and on your PATH. Pre-build those environments once with viralunity setup --pipelines all (see First-time environment setup below).

Clone and create the environment

To work from a source checkout instead (required for development, and for the tutorial, which references bundled example files):

git clone https://github.com/InstitutoTodosPelaSaude/ViralUnity.git
cd ViralUnity/
conda env create -f environment.yml
conda activate viralunity

Or with micromamba (recommended on macOS with Apple Silicon):

micromamba env create -f environment.yml --platform osx-64
micromamba activate viralunity

Warning

On macOS with Apple Silicon (M1 or later), the viralunity/scripts/envs/clair3.yaml environment may not install correctly due to compatibility constraints in the clair3 dependencies.

Troubleshooting

CreateCondaEnvironmentException with a repodata_shards.msgpack.zst 404

If the first pipeline run aborts on Creating conda environment .../qc.yaml ... with a chained HTTPError: 404 for repodata_shards.msgpack.zst followed by a JSONDecodeError, you are hitting a known incompatibility between conda 26.x’s libmamba shards path and bioconda (which does not publish shards). environment.yml already pins conda<26 and conda-libmamba-solver<26 to avoid this, so the fix is to rebuild the viralunity env from the pinned file:

conda deactivate
conda env remove -n viralunity
conda env create -n viralunity -f environment.yml
conda activate viralunity
pip install -e .

If you cannot rebuild the env (for example, on a shared cluster install), the manual escape hatch is to fall back to the classic solver:

conda config --set solver classic

This is why environment.yml pins conda<26 / conda-libmamba-solver<26: newer solvers query repodata_shards.msgpack.zst from bioconda (not published) and mishandle the resulting 404. If you hit environment-creation errors, set the classic solver as shown above.

Verify the installation

viralunity --version
viralunity --help

First-time environment setup

After installing ViralUnity, build the per-rule conda environments once with:

viralunity setup --pipelines all

This downloads and resolves every sub-pipeline dependency into ~/.cache/viralunity/conda-envs/ (override with --conda-prefix PATH, or set $VIRALUNITY_CONDA_PREFIX). Future viralunity consensus / viralunity meta runs reuse the cached envs and do not need to re-create them per working directory, which both speeds up first runs and isolates env-creation failures from real pipeline runs.

Run viralunity setup --pipelines consensus-illumina --dry-run first to inspect what would be built.

Development install

To work on ViralUnity itself, install the optional dev extras (linters and tests):

pip install -e ".[dev]"

See CONTRIBUTING.md for the full development workflow.