Installation

Installation#

This page installs the Conda-compatible BASALT repository. BASALT depends on several compiled bioinformatics programs, quality-control databases, and trained model files. A successful Python import alone is therefore not a complete installation test.

Platform and resources#

Requirement

Supported or practical value

Operating system

Linux x86-64

Python

3.12

CPU

8 threads minimum; 32 or more recommended for routine datasets

Memory

128 GB practical starting point; 256 GB or more for large or complex runs

Storage

Dataset-dependent; allow space for mappings, candidate bins, reassemblies, and archives

macOS and Windows are not supported as native execution platforms. Use a Linux host, cluster, virtual machine, or compatible container runtime.

Conda-compatible installation#

1. Clone the repository#

git clone --depth 1 https://github.com/PKU-EMBL/BASALT.git
cd BASALT

The shallow clone downloads only the current revision and is sufficient for an installation. Omit --depth 1 when the full history is required for development or historical comparison.

Record the version you installed:

git rev-parse HEAD

2. Create the environment#

Micromamba is the recommended package manager because it uses the libmamba solver, downloads packages in parallel, and does not require a Python-equipped base environment:

micromamba create -n basalt -f basalt_environment.yml \
  --strict-channel-priority --yes

Current Conda is an equivalent fallback:

CONDA_CHANNEL_PRIORITY=strict \
  conda env create -n basalt -f basalt_environment.yml \
  --solver libmamba --yes

basalt_environment.yml is the sole repository environment definition. It uses only conda-forge and bioconda; the commands above enforce strict channel priority without editing global configuration. The file resolves the base bioinformatics and scientific-Python stack in one Conda transaction, selects the CPU-generic PyTorch build with OpenBLAS, and uses the headless Matplotlib base package. It deliberately avoids a second pip or uv dependency transaction, which could replace the solved stack with large CUDA or graphical-interface dependencies. Optional extra binners remain separate installations. The legacy CheckM package is intentionally excluded because its dependency stack conflicts with the maintained Python 3.12/CheckM2 route; install it in a separate compatible environment only when -q checkm is required.

If package access is slow or unreliable in mainland China, use the network-aware installer rather than changing this portable YAML or the global Conda configuration.

3. Install the BASALT command#

Install directly through the selected manager without depending on shell activation:

micromamba run -n basalt bash install.sh
# or: conda run -n basalt bash install.sh

The script copies the BASALT programs into $CONDA_PREFIX/bin and creates the BASALT launcher. Re-run the installer after updating the repository because this is a copied installation, not an editable package.

Optional extra binners are not part of the base installation. In particular, -e l uses the PKU-EMBL/LorBin-BASALT-Extrabinner in-house fork, which must be installed and validated separately. Do not add it to the portable BASALT environment YAML without re-solving and testing the complete stack; follow the pinned-source procedure in Extra binners.

4. Download the trained models#

Choose a persistent absolute model directory outside temporary or run-specific storage, and keep the path free of shell metacharacters. Automatic mode first uses the official PKU-EMBL/BASALT_WEIGHT repository, whose client supports concurrent and resumable downloads, and then falls back to the legacy Figshare ZIP:

micromamba run -n basalt \
  BASALT_models_download.py \
  --source auto \
  --path /absolute/persistent/path/BASALT_WEIGHT

Conda users can replace micromamba run with conda run. A public Hugging Face repository does not require login. The downloader pins the model revision associated with this BASALT release instead of following a moving main branch. Automatic mode bounds its Hugging Face reachability check at 15 seconds before falling back to Figshare; use --hf-timeout SECONDS to adjust that check for the site network. To force one source or use a file obtained through another route:

# Official Hugging Face only
BASALT_models_download.py --source huggingface --path "$BASALT_WEIGHT"

# Existing ZIP, including a manually downloaded Baidu Netdisk copy
BASALT_models_download.py --source archive \
  --archive /path/to/BASALT.zip \
  --path "$BASALT_WEIGHT"

# Site-operated object storage or another trusted URL
BASALT_models_download.py --source url \
  --url https://example.org/BASALT.zip \
  --path "$BASALT_WEIGHT"

The downloader checks both the five top-level *_ensemble.csv descriptors and their corresponding checkpoint directories. Verify the result independently:

find /absolute/persistent/path/BASALT_WEIGHT \
  -maxdepth 1 -name '*_ensemble.csv' | wc -l

Expected output: 5.

After verification, place one authoritative export in ~/.bashrc so interactive logins and Bash-based batch jobs resolve the same models:

printf '%s\n' \
  'export BASALT_WEIGHT="/absolute/persistent/path/BASALT_WEIGHT"' \
  >> ~/.bashrc
source ~/.bashrc

test -d "$BASALT_WEIGHT"
find "$BASALT_WEIGHT" -maxdepth 1 -name '*_ensemble.csv' | wc -l

Before appending, search ~/.bashrc for an older BASALT_WEIGHT definition and update or remove it; multiple exports make interactive and scheduled runs difficult to audit. Some schedulers do not source ~/.bashrc for non-interactive jobs. In that case, source it explicitly in the job script or export the same absolute path there.

5. Configure CheckM2#

CheckM2 is the default quality-control backend:

checkm2 database --download

If CheckM2 does not discover the database automatically, set the path to its DIAMOND database:

export CHECKM2DB=/absolute/path/to/CheckM2_database/uniref100.KO.1.dmnd

The legacy CheckM backend is selected with -q checkm. CheckM can impose a different Python and dependency stack from the maintained CheckM2 route. Validate it in a compatible environment or container, install its database, and set the location required by that installation, commonly CHECKM_DATA_PATH.

6. Verify the executable stack#

BASALT --help

command -v \
  BASALT checkm2 metabat2 SemiBin2 bowtie2 bwa samtools \
  minimap2 spades.py unicycler blastn makeblastdb

Then record the environment for provenance:

micromamba env export -n basalt > basalt-environment.yml
# or: conda env export -n basalt --no-builds > basalt-environment.yml

Warning

The Conda edition documented here does not implement BASALT --version or BASALT --check-deps. Those options belong to BASALT-Air. Use BASALT --help, command -v, explicit tool version commands, and the tutorial smoke test.

Singularity execution#

The upstream repository has historically described a prebuilt basalt.sif image, but its former Google Drive endpoint returned HTTP 404 during this documentation update. Use the Conda installation above unless you already possess a trusted image or the maintainers publish a new verified artifact. Follow the upstream repository for distribution updates.

If you already have an image, record where it came from and verify its checksum before production use.

Verify the image before production use:

singularity run basalt.sif BASALT --help
singularity run basalt.sif checkm2 --help
singularity inspect basalt.sif > singularity-inspect.txt

Run from a dedicated directory and bind all required storage explicitly:

cd /project/basalt_run

singularity run \
  --bind /project:/project \
  basalt.sif \
  BASALT \
  -a assembly.fasta \
  -s sample_R1.fastq,sample_R2.fastq \
  -t 32 -m 128 --mode new -o study_basalt

Preserve an image checksum with each analysis:

sha256sum basalt.sif > basalt.sif.sha256

On a cluster, make the bind explicit even if the runtime normally auto-binds the current directory. Confirm that inputs, the working directory, databases, and BASALT_WEIGHT are visible inside the container before starting a long job. Run under the site scheduler or a persistent session, capture stdout and stderr, and do not rely on terminal persistence as a substitute for checkpoint and output auditing.

China mainland#

BASALT_setup_China_mainland.py handles the environment, script installation, and model weights as one recoverable workflow. It prefers an installed micromamba, then mamba, then Conda. The following command downloads the official standalone micromamba only when micromamba is unavailable, stores its shared package cache under ~/micromamba, probes several mirror endpoints, and downloads weights from Hugging Face first:

python3 BASALT_setup_China_mainland.py \
  --manager micromamba \
  --bootstrap-micromamba \
  --mirror auto \
  --env-name basalt

The bootstrapped binary is placed at ~/.local/bin/micromamba; the installer does not initialize or edit the shell. It also does not run conda config, edit ~/.condarc, edit pip configuration, or change environment files to mode 777. Activate later with the path printed at completion, or continue using micromamba run -n basalt COMMAND.

Inspect the exact commands without changing the system:

python3 BASALT_setup_China_mainland.py \
  --manager micromamba \
  --bootstrap-micromamba \
  --mirror tuna \
  --model-source none \
  --dry-run

Mirror selection#

Option

Conda channels

Matching temporary PyPI index

Intended use

--mirror auto

probes TUNA, BFSU, USTC, then upstream

follows the selected preset

default for variable networks

--mirror tuna

TUNA conda-forge and bioconda

TUNA PyPI

stable manual selection

--mirror bfsu

BFSU conda-forge and bioconda

BFSU PyPI

alternative education-network route

--mirror ustc

USTC dynamic caches for conda-forge and bioconda

USTC PyPI

community-channel-only environment

--mirror upstream

official conda.anaconda.org

inherited/default PyPI

VPN, proxy, or international route

The presets follow the current TUNA, BFSU, and USTC Anaconda mirror guidance. USTC currently documents dynamic caches for conda-forge and bioconda, which is sufficient because the maintained BASALT environment no longer depends on defaults or the historical esteinig channel.

For an institutional mirror, repeat --channel in decreasing-priority order and optionally set the PyPI endpoint:

python3 BASALT_setup_China_mainland.py \
  --channel https://mirror.example.edu/anaconda/cloud/conda-forge \
  --channel https://mirror.example.edu/anaconda/cloud/bioconda \
  --pip-index-url https://mirror.example.edu/pypi/simple

Do not combine packages from different channel stacks in one solved environment. If a mirror is reachable but lacks a required artifact, rerun with --update --mirror OTHER after confirming the selected route, or create a new environment under a different name. Existing package caches can be used with --offline.

Weight fallbacks#

Automatic mode uses Hugging Face first and Figshare second. To create only the software environment, pass --model-source none. Model files are additionally available from Baidu Netdisk with extraction code embl; after manual download, keep the original ZIP and run:

python3 BASALT_setup_China_mainland.py \
  --model-source archive \
  --model-archive /absolute/path/BASALT.zip \
  --model-dir /persistent/path/BASALT_WEIGHT

The same local archive works independently of the installer:

BASALT_models_download.py \
  --source archive \
  --archive /absolute/path/BASALT.zip \
  --path /persistent/path/BASALT_WEIGHT

Use --hf-endpoint only for a trusted Hugging Face-compatible service operated or approved by your institution, and retain the pinned --revision plus model-file checksums in the run record. --hf-timeout controls the initial reachability check. Proxy variables such as HTTPS_PROXY are inherited automatically.

After installation, export the final environment, record the selected mirror, and verify every external executable. Database downloads are separate from package and model installation; run checkm2 database --download through the network route approved for the compute site.

Updating BASALT#

The installer copies scripts into the environment. Update and reinstall them explicitly:

cd /path/to/BASALT
git pull --ff-only
git rev-parse HEAD
python3 BASALT_setup_China_mainland.py \
  --source-dir . \
  --env-name basalt \
  --update \
  --model-source none

Start new analyses in a new working directory after an update. Resuming a checkpoint with different code, model weights, databases, or external-tool versions weakens reproducibility and may produce incompatible intermediates.

Next step#

Run the quick start, then the tutorial with the public demo dataset.

Contents