Skip to content

Installation

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

Quick install

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.14.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, cu130):

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

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.14.x (torch>=2.14,<2.15). Wheels are ABI-matched to that minor, so keep your PyTorch on 2.14.x.

Source builds use the same supported PyTorch 2.14.x lane. Other PyTorch minor versions are not supported by this release.

Python 3.15 on macOS

PyTorch 2.14's cp315 macOS wheels were built against CPython 3.15.0b3 headers and segfault on the first tensor operation outside the main thread (pytorch/pytorch#200779). PyTorch 2.14 has no fixed rebuild, so the 1.3 release series does not publish cp315 macOS wheels; use Python 3.14 or the Linux cp315 wheel until PyTorch 2.15.

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. Without it, .bz2 inputs raise an actionable error. Likewise, CFITSIO opens https:// and ftps:// URLs through libcurl when the build finds it; without it those URLs raise an actionable ValueError instead of a generic open failure.

To check what a build was compiled with, print the two build flags. They live on the private compiled module, so treat this as a diagnostic, not an API:

python -c "import torchfits._C as c; print('bzip2:', c.HAS_BZIP2, 'https/ftps:', c.HAS_CURL)"

Building from source is only needed when developing torchfits or using a platform without a published wheel. Use PyTorch 2.14.x.

Prerequisites

sudo apt install build-essential cmake ninja-build

xcode-select --install
brew install cmake ninja

Windows is unsupported. There are no wheels, and the native extension is not tested with MSVC. Use WSL2, Linux, or macOS.

Build steps

git clone https://github.com/astroai/torchfits.git
cd torchfits
./extern/vendor.sh --cfitsio-version extern/VERSIONS.txt   # downloads the pinned CFITSIO

# Install build dependencies and compile against your environment
pip install torch numpy pyarrow 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, use pixi 0.82.0 (requires-pixi in pixi.toml):

pixi install --locked
pixi run test           # build the extension, then the full suite
pixi run lint           # ruff linter and formatter

pixi run test rebuilds the extension in the default environment. Astropy and fitsio are not installed here; comparisons against them run in torchfits-harness.

Optional dependencies

Extra Included packages Purpose
torchfits[dev] pytest, ruff, mypy, pandas, matplotlib Library development toolchain
torchfits[test] pytest, pytest-cov, psutil Unit testing extras (pip install torchfits[test]); PyArrow comes from the base package
torchfits[docs] zensical Building the documentation site
torchfits[examples] matplotlib Running tutorial scripts

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 and aarch64, glibc 2.28+) on CPython 3.11–3.15 and macOS 14+ (Apple Silicon arm64) on CPython 3.11–3.14. Windows, musl Linux, older glibc, older macOS, and x86_64 macOS are unsupported.

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 --cfitsio-version extern/VERSIONS.txt fails

The script requires --cfitsio-version; run with no arguments it prints its usage and exits 1. Beyond that, ensure curl and tar are installed and reachable (a sha256 mismatch against the pinned CFITSIO tarball also fails here, by design). If behind a proxy, set HTTPS_PROXY.