This release is a pre-release and may not be stable for production use.
torchfits
torchfits is high-performance FITS I/O: read and write FITS as tensors and tables — cutouts, filters, and a shell CLI (C++ engine, vendored CFITSIO). Optional datasets / transforms sit on top; you do not need an ML workflow to benefit.
Current: 1.0.0 — built for the
PyTorch 2.13 lane (wheels are ABI-matched to the torch minor they ship
for). Docs: stable (latest v* tag) ·
edge (main tip).
Install
torchfits wheels are ABI-matched to the PyTorch 2.13.x minor, and the
wheel's metadata pins that range (torch>=2.13,<2.14) — so the install
command needs no torch restriction: pip installs or upgrades torch for you.
pip install torchfits
Works with any Python 3.10+ and any installed PyTorch ≥ 2.10: if you already have torch 2.13.x (any flavor — CPU or CUDA), it is left untouched; an older minor is upgraded to 2.13.x automatically (the torch C++ ABI is per-minor, so torchfits must load against its lane). Pin explicitly only when you must keep a specific torch minor:
pip install torchfits "torch>=2.13,<2.14"
Requires Python 3.10+ and PyTorch ≥ 2.10 (wheels are built for the 2.13.x lane; pip aligns your torch automatically). Pre-built wheels for Linux x86_64 and macOS arm64 (CFITSIO is vendored).
Choose a PyTorch flavor in one line:
| You want | Command |
|---|---|
| Default (CUDA + CPU) | pip install torchfits |
| CPU-only (thin) | pip install torchfits "torch>=2.13,<2.14" --extra-index-url https://download.pytorch.org/whl/cpu |
| CUDA build (e.g. cu129) | pip install torchfits "torch>=2.13,<2.14" --extra-index-url https://download.pytorch.org/whl/cu129 |
The [cpu] / [cuda] extras pin the matching torch build exactly
(torch==2.13.0+cpu / torch==2.13.0+cu129) after a one-time index setting
(PIP_EXTRA_INDEX_URL / pip.conf). Both extras are Linux-only — on
macOS they are no-ops (MPS ships inside the default wheel). In zsh, quote the
extra (pip install 'torchfits[cpu]'). Details:
Install.
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 in C++ | torchfits.table.read(..., where="MAG < 20") |
| Columns as tensors | torchfits.table.read_torch(..., where=...) |
| 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 |
| Benchmarks | Methodology and scorecards |
| Changelog | Release notes |
Coding agents can use the docs site or this repo; humans should still skim Quick start or Python workflows.
Develop
Pixi-first (do not use bare python for project work):
git clone https://github.com/astroai/torchfits.git
cd torchfits
pixi install
pixi run preflight-push # fast gate while editing
pixi run test # full unit suite
pixi run ci-local # pre-push parity
Agent conventions: AGENTS.md. Release process: docs/release.md.
License
1 maintainer
Release files for torchfits 1.0.0rc5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| torchfits-1.0.0rc5.tar.gz | 4.4 MB | Details |
Built distributions (wheels)
Total release size: 12.6 MB
Release files / torchfits-1.0.0rc5.tar.gz
| Download URL | torchfits-1.0.0rc5.tar.gz |
|---|---|
| Size | 4.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ffda89b0b47e1d6971dd5abd5ab21ca0989fb940cae6b12792a3d333dd7855dd
|
|
BLAKE2b-256 checksum How to use checksums |
b86cef6db962a0e5591ff0eb9d9a6821e03e9f324f21c9b1005f34ba39188227
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / torchfits-1.0.0rc5-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | torchfits-1.0.0rc5-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
55fdda62c1c7ea1a1fbe12e463df2c5f832c2f6ddc69634b20263de05afd6e4e
|
|
BLAKE2b-256 checksum How to use checksums |
72358d58ec936dd5f277dabb46c317b1378da092e0e3ca8f5040fc7d50e15783
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / torchfits-1.0.0rc5-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | torchfits-1.0.0rc5-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 971.9 kB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
52440bb72e8cf0deb68b10939ac9433428da504abd07cb69f9cc21ada77ced50
|
|
BLAKE2b-256 checksum How to use checksums |
215a7451e97313b98000f9fa3e7b9b7a86355939b809245767d70535509fd0f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / torchfits-1.0.0rc5-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | torchfits-1.0.0rc5-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
c04ed9e397fbc67813684da54d8e4d6f91dfbabe994a0e8e849eaabc842c7695
|
|
BLAKE2b-256 checksum How to use checksums |
4fa3a2d5d6e210a9a95cac19c060e48ba918535170d502e82c745b65a1f17087
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / torchfits-1.0.0rc5-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | torchfits-1.0.0rc5-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 971.8 kB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
674f6a123310c94b8bb99f1f72d823e7b73e178c69998785f2dd2501b73d7d83
|
|
BLAKE2b-256 checksum How to use checksums |
5244966a66effa92bb8522fde7d6c2a4298fe04acb3d84c855f66760a5afb857
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / torchfits-1.0.0rc5-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | torchfits-1.0.0rc5-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
7b42dd7be9def4d585c380ee9cd774d97acdc5f6725c46b7d7ebda47076c3ee3
|
|
BLAKE2b-256 checksum How to use checksums |
0667dba977783197680aa0cdd67f42e2d674ad7091bbc092fad6d87ef8970470
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / torchfits-1.0.0rc5-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | torchfits-1.0.0rc5-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 973.3 kB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
14c400dda55723bf37ef18a84ff8e1a8f338f901f7de51585e3574c2fae9afcc
|
|
BLAKE2b-256 checksum How to use checksums |
a2734e4cf1df371a195d29516c6b2d426a4a75f0114373d0f962a8ef91cdacaf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / torchfits-1.0.0rc5-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | torchfits-1.0.0rc5-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
6129cc4f9a03ca5c788a0a96252a6c96258f20e9dea16abe3f2a10d6d519bf46
|
|
BLAKE2b-256 checksum How to use checksums |
7d0f154fe528a5514bbbef08c9faa7cca10f78e7f2ae83ea9d4a8d32e138c9f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency logRelease files / torchfits-1.0.0rc5-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | torchfits-1.0.0rc5-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 973.5 kB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
9ff1ca4d8bae4eb04bd30b1e1b3d2b482003acd744188ec4721cb2ccfef084d8
|
|
BLAKE2b-256 checksum How to use checksums |
49e6ab8f7556b52a3ad8370e32d9267223c7a578c3973113e1420a0c80100691
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.
Transparency log
