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
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
