STARNet Installation Guide

STARNet is installed from source. The recommended workflow below clones the official STARNet repository, creates a fresh environment, installs the pinned dependencies, and verifies the import.

1. Prepare

Install prerequisites (git, conda or micromamba).

2. Install

Create a reproducible starnet environment and install STARNet.

3. Verify

Activate the environment and confirm that STARNet works correctly.

Prerequisites

  • Linux is the validated platform. macOS and Windows through WSL may work but are not actively tested.

  • Python 3.11 — managed by conda/micromamba, not your system Python.

  • git — install git

  • conda (recommended) or micromamba:

  • curl — needed by the Miniforge installer (pre-installed on most Linux distributions).

  • Disk space: ~3 GB for packages (mainly PyTorch + CUDA libraries).

  • GPU: NVIDIA GPU with driver supporting CUDA ≥ 12.8 (PyTorch 2.10 ships with CUDA 12.8 libraries).

Check what you already have
git --version
conda --version || micromamba --version
nvidia-smi  # check GPU driver / CUDA version

Quick Install

git clone https://github.com/DBinary/STARNet.git
cd STARNet
bash install.sh

This script auto-detects conda or micromamba, creates the environment, installs all dependencies, and verifies the import.

Manual Install

If you prefer micromamba, or want to step through the commands individually:

git clone https://github.com/DBinary/STARNet.git
cd STARNet
conda env create -n starnet -f environment-conda.yml
conda run -n starnet python -m pip install -r requirements-review.txt
conda run -n starnet python -m pip install --no-deps -e .
conda activate starnet

git clone https://github.com/DBinary/STARNet.git
cd STARNet
micromamba env create -n starnet -f environment-conda.yml
micromamba run -n starnet python -m pip install -r requirements-review.txt
micromamba run -n starnet python -m pip install --no-deps -e .
micromamba activate starnet

Note

The pip install -r requirements-review.txt step installs all runtime dependencies (~200 packages). The subsequent pip install --no-deps -e . only registers STARNet itself — it assumes the requirements step succeeded, so do not skip or reorder these steps.

Verify

After activation, run these checks:

# 1. Basic import and key submodules
import STARNet as ST
from STARNet import grn, model, pl, pp

# 2. GPU availability (required for GRN workflows)
import torch
print("CUDA available:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("GPU:", torch.cuda.get_device_name(0))
else:
    print("WARNING: No GPU detected. Training will fall back to CPU.")

Expected output on a GPU machine:

CUDA available: True
GPU: NVIDIA GeForce RTX 4090

If the import succeeds without errors, STARNet is installed correctly.

Troubleshooting

Slow downloads / hash mismatches

STARNet downloads ~3 GB of GPU-enabled PyTorch dependencies. If https://pypi.org/simple is slow in your region, you can temporarily use a mirror. However, requirements-review.txt pins exact SHA256 hashes, and some mirrors serve wheels with mismatched hashes, causing errors like:

THESE PACKAGES DO NOT MATCH THE HASHES

If you hit this, remove the -i flag and retry with the default PyPI index:

conda run -n starnet python -m pip install \
  -r requirements-review.txt

micromamba run -n starnet python -m pip install \
  -r requirements-review.txt

libstdc++ / CXXABI Errors

On some systems, the system libstdc++ may be picked before the active environment, causing errors for optional genomics tooling. If this happens, export the active environment library path before running GRN inference:

export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"

GPU

GPU support is enabled by default because STARNet’s GRN workflows depend on GPU-accelerated model components. If torch.cuda.is_available() returns False:

  1. Check your NVIDIA driver: nvidia-smi

  2. Verify driver supports CUDA ≥ 12.8 (PyTorch 2.10 requirement)

  3. Older GPUs (compute capability < 7.0) may require a CPU-only PyTorch build

For optional CuPy acceleration, install the CuPy build matching your CUDA toolkit after STARNet is installed.