Installation¶

torchfits is distributed as prebuilt binary wheels for Linux (x86_64, aarch64) and macOS (Apple Silicon arm64) supporting Python 3.10–3.14. CFITSIO is vendored directly into the wheels, so no C++ compiler, system libraries, or manual build steps are required.

Quick install¶

1. Standard install (CUDA + CPU auto-detection) — Recommended¶

For standard environments (Linux with NVIDIA GPU, CPU-only Linux, or macOS Apple Silicon):

pip install torchfits

• On Linux with an NVIDIA GPU: device="cuda" copies the host-decoded tensor onto CUDA.
• On Linux without a GPU: falls back to CPU automatically (device="cpu").
• On macOS (Apple Silicon): device="mps" copies the host-decoded tensor onto Metal.

2. CPU-only install (Minimal footprint)¶

On headless servers, CI runners, or containers where CUDA runtime libraries are not needed, use the lightweight CPU index with [cpu] extra:

pip install "torchfits[cpu]" --extra-index-url https://download.pytorch.org/whl/cpu
# Or explicitly pinning the CPU PyTorch build:
pip install torchfits "torch==2.13.0+cpu" --extra-index-url https://download.pytorch.org/whl/cpu

3. Specific CUDA toolkit versions¶

To match a specific CUDA version installed on your system (e.g. cu126, cu129, cu130):

pip install "torchfits[cuda]" --extra-index-url https://download.pytorch.org/whl/cu129
# Or explicitly pinning the CUDA PyTorch build:
pip install torchfits "torch==2.13.0+cu129" --extra-index-url https://download.pytorch.org/whl/cu129

PyTorch Version Compatibility¶

The PyPI release is built against one PyTorch minor version at a time (an "ABI lane"); the current lane is PyTorch 2.13.x (torch>=2.13,<2.14). Wheels are ABI-matched to that minor, so keep your PyTorch on 2.13.x.

If you must stay on an older PyTorch (≥ 2.10), install from source against your environment (see below) — prebuilt wheels are not published for other lanes (PyTorch minor versions).

Verify your installation¶

import torchfits
import torch

print(f"torchfits {torchfits.__version__} with torch {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")

torchfits info --help

Building from source¶

Builds link libbz2 when available (conda prefix or system via CMake), which enables BZIP2_1 tile compression and transparent reading of whole-file .bz2 FITS (torchfits._C.HAS_BZIP2 reports the capability). Without it, .bz2 inputs raise an actionable error.

Building from source is only needed if you are developing torchfits or targeting a custom PyTorch build (≥ 2.10).

Prerequisites¶

• Python 3.10+
• C++17 compiler (GCC 10+, Clang 14+, MSVC 2019+)
• CMake 3.21+ and Ninja
• PyTorch ≥ 2.10 and NumPy

sudo apt install build-essential cmake ninja-build

xcode-select --install
brew install cmake ninja

Build steps¶

git clone https://github.com/astroai/torchfits.git
cd torchfits
./extern/vendor.sh      # downloads vendored CFITSIO

# Install build dependencies and compile against your environment
pip install numpy scikit-build-core nanobind
pip install --no-deps --no-build-isolation -e .

To link against a system-installed CFITSIO instead of the vendored source:

pip install -e . --no-deps --no-build-isolation --config-settings=cmake.args="-DTORCHFITS_USE_VENDORED_CFITSIO=OFF"

Development setup (Pixi)¶

For local development and running the test suite, we recommend pixi:

pixi install
pixi run test           # run test suite
pixi run lint           # ruff linter and formatter
pixi run bench-all      # benchmarks

Optional dependencies¶

PyArrow is installed automatically for tabular operations (torchfits.table). Interoperability with Pandas, Polars, and DuckDB is supported seamlessly:

pip install pandas polars duckdb

Troubleshooting¶

OMP: Error #15: Initializing libomp.dylib

Two OpenMP libraries are loaded in the same process — typical on macOS when PyTorch's libomp meets Homebrew or conda llvm-openmp. Importing torchfits sets KMP_DUPLICATE_LIB_OK=TRUE before PyTorch loads. Import torchfits first, or export that variable in the shell before import torch:

export KMP_DUPLICATE_LIB_OK=TRUE

No matching distribution found for torchfits

Prebuilt binary wheels are available for Linux (x86_64, aarch64) and macOS (Apple Silicon arm64) on CPython 3.10–3.14. Windows and x86_64 macOS are unsupported (no wheels, no tested MSVC recipe).

ImportError: ... ABI mismatch

The binary extension was built against a different PyTorch minor version than the one currently active in Python. Either install the matching prebuilt wheel for your PyTorch version or rebuild from source.

./extern/vendor.sh fails

Ensure curl and tar are installed and reachable. If behind a proxy, set HTTPS_PROXY.