Install & Compatibility
Where this runs
tested against v2.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 9.8s · import 3.284s · 294MB
277MB installed
● package 277MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DAOStarFinder
✓ from photutils.detection import DAOStarFinder
IRAFStarFinder
✓ from photutils.detection import IRAFStarFinder
Background2D
✓ from photutils.background import Background2D
MedianBackground
✓ from photutils.background import MedianBackground
detect_sources
✓ from photutils.segmentation import detect_sources
deblend_sources
✓ from photutils.segmentation import deblend_sources
CircularAperture
✓ from photutils.aperture import CircularAperture
aperture_photometry
✓ from photutils.aperture import aperture_photometry
PropertiesCatalog
✓ from photutils.segmentation import PropertiesCatalog
✗ from photutils.segmentation import SourceProperties
SourceProperties and SourceCatalog were removed in v2.0.0; use PropertiesCatalog instead.
Gaussian2D
✓ from astropy.modeling.models import Gaussian2D
✗ from photutils.psf import Gaussian2D
PSF models were removed from photutils.psf in v2.0.0; use astropy.modeling.models instead.
This quickstart demonstrates a basic `photutils` workflow: generating synthetic image data, estimating and subtracting the background, detecting point sources using DAOStarFinder, and performing aperture photometry on the detected sources. This covers fundamental steps in analyzing astronomical images.
import numpy as np
from astropy.stats import sigma_clipped_stats
from photutils.detection import DAOStarFinder
from photutils.background import Background2D, MedianBackground
from photutils.aperture import CircularAperture, aperture_photometry
# Create dummy data (replace with your actual FITS data)
data = np.random.rand(100, 100) * 100
y, x = np.mgrid[0:100, 0:100]
data += 500 * np.exp(-((x - 20)**2 + (y - 20)**2) / (2 * 5**2)) # Add a star
data += 700 * np.exp(-((x - 70)**2 + (y - 80)**2) / (2 * 7**2)) # Add another star
# 1. Estimate background
mean_bkg, median_bkg, std_bkg = sigma_clipped_stats(data, sigma=3.0)
bkg = Background2D(data, (50, 50), filter_size=(3, 3),
bkg_estimator=MedianBackground())
data_subtracted = data - bkg.background
# 2. Detect sources
finder = DAOStarFinder(fwhm=5.0, threshold=3.0 * std_bkg)
sources = finder(data_subtracted)
if sources is None:
print("No sources found. Adjust DAOStarFinder parameters.")
else:
print(f"Detected {len(sources)} sources:")
for col in sources.colnames:
sources[col].info.format = '%.8g' # for consistent output
print(sources)
# 3. Perform aperture photometry
positions = (sources['xcentroid'], sources['ycentroid'])
aperture = CircularAperture(positions, r=8.0)
phot_table = aperture_photometry(data_subtracted, aperture)
print("\nAperture Photometry:")
for col in phot_table.colnames:
phot_table[col].info.format = '%.8g' # for consistent output
print(phot_table)
Errors
Common errors & fixes
AttributeError: 'module' object has no attribute 'Gaussian2D'
Attempting to import PSF models (like Gaussian2D) from `photutils.psf` after the v2.0.0 release.
fixReplace `from photutils.psf import Gaussian2D` with `from astropy.modeling.models import Gaussian2D`.
NameError: name 'SourceProperties' is not defined
Using the `SourceProperties` or `SourceCatalog` classes, which were removed in `photutils` v2.0.0.
fixImport and use `from photutils.segmentation import PropertiesCatalog` instead, adapting your code to its API.
TypeError: 'astropy.units.quantity.Quantity' object cannot be interpreted as an integer
Passing an `astropy.units.Quantity` object (data with units) directly to a `photutils` function that expects a plain numerical array.
fixExtract the numerical value from the `Quantity` using `.value` before passing it to the function (e.g., `data_quantity.value`). Ensure you handle units appropriately in subsequent calculations.
ImportError: cannot import name 'PixelAperture' from 'photutils.aperture'
Attempting to import the generic `PixelAperture` class after its removal in `photutils` v2.0.0.
fixFor geometrically shaped source apertures, use specific classes like `CircularAperture`, `RectangularAperture`, or `EllipticalAperture`. For pixel-based *background* apertures, use `photutils.aperture.BkgPixelAperture`.
Upgrade
Version history
3.0.0latest on PyPI · released Apr 17, 2026
Audit
Dependencies
astropyrequiredCore dependency for astronomical data structures, units, WCS, and modeling.
numpyrequiredFundamental for numerical array operations.
scipyrequiredUsed for various scientific computing tasks, including PSF fitting and filtering.
matplotliboptionalOptional dependency for visualization and plotting in examples and user scripts.