torchfits

Read and write FITS files as PyTorch tensors and Arrow tables. Cutouts, where= filters, and a shell CLI are included. CFITSIO is in the wheel. Arrow columns are zero-copy views over the decoded buffers, and header or Arrow reads do not import PyTorch.

Prebuilt wheels for Python 3.11–3.15 on Linux and 3.11–3.14 on macOS, with PyTorch 2.14.x: Linux (x86_64, aarch64) and macOS Apple Silicon.

Docs: stable · edge (main tip)

Install

pip install torchfits

Prebuilt wheels decode FITS on the host, then device="cuda" / "mps" copies the tensor onto the GPU when those runtimes are available. For CPU-only installs, custom CUDA builds, or other PyTorch versions, see the Installation guide.

At a glance

Task	API
Image → tensor	torchfits.read_tensor("img.fits", device="cuda")
Write a tensor	torchfits.write("out.fits", tensor)
Filter a catalog	torchfits.table.read(..., where="MAG < 20")
Columns as tensors	torchfits.table.read_torch(..., where=...)
Header without PyTorch	torchfits.read_header("img.fits")
Open a MEF	with torchfits.open("mef.fits") as hdul: …
Train	FitsImageDataset + make_loader(..., num_workers=4)
Shell	torchfits info / header / convert / cutout / …

Quick start

import torchfits

tensor = torchfits.read_tensor("image.fits", hdu=0, device="cpu")

table = torchfits.table.read(
    "catalog.fits",
    columns=["RA", "DEC", "MAG_G"],
    where="MAG_G < 20.0",
)

torchfits info science.fits
torchfits convert catalog.fits out.parquet --hdu 1
torchfits cutout 'science.fits[100:256,100:256]' cutout.fits

Learn more

Documentation	Quick start, Python workflows, API, CLI
Python workflows	Which API for images, tables, cutouts, training
Examples	Runnable scripts + transform plots
Evaluation	Where parity and benchmark notes live
Changelog	Release notes

Develop

Pixi-first (do not use bare python for project work):

git clone https://github.com/astroai/torchfits.git
cd torchfits
pixi install --locked
pixi run preflight-push   # fast gate while editing
pixi run test             # full unit suite
pixi run current-source-gate  # locked environment + complete local gate

Agent conventions: AGENTS.md. Release process: docs/release.md.

License

MIT