CRDS - Calibration Reference Data System

13.1.16 verified Fri May 01 auth: no python

CRDS (Calibration Reference Data System) manages calibration reference files for HST, JWST, and Roman telescopes. It provides tools for selecting, downloading, and validating reference files. Version 13.1.16 supports Python >=3.7 and is actively maintained with regular releases aligned with telescope operations.

pip install crds

Common errors

error ImportError: cannot import name 'BestReferences' from 'crds' ↓

cause Outdated crds version (before 10.0) that doesn't have BestReferences class.

fix

Upgrade crds to latest: pip install --upgrade crds

error crds.core.exceptions.CrdsNetworkError: Unable to connect to CRDS server ↓

cause No internet access or incorrect CRDS_SERVER_URL. CRDS defaults to public STScI server; if blocked, set a mirror.

fix

Check network, set CRDS_SERVER_URL to a reachable server (e.g., https://crdsserver.stsci.edu), or use a local mirror.

error KeyError: 'INSTRUMENT' ↓

cause Observation dictionary missing required key 'INSTRUMENT'.

fix

Include all required keys: INSTRUMENT, DETECTOR, DATE-OBS. Example: obs = {'INSTRUMENT': 'NIRCam', 'DETECTOR': 'NRCA1', 'DATE-OBS': '2023-01-01'}

error crds.core.exceptions.CrdsLookupError: No matching reference file found ↓

cause No reference file for the given context and observation parameters. Could be obsolete context or incorrect parameters.

fix

Use a more recent context (pmap) or check that observation parameters match available reference files. Try context = 'jwst_ops.pmap' for latest.

Warnings

breaking CRDS 11.x dropped Python 2 support. Current versions require Python >=3.7. ↓

fix Upgrade to latest crds and use Python 3.7+. If you need Python 2 compatibility, stay on legacy versions (not recommended).

deprecated The function `crds.getreferences()` is deprecated. Use `BestReferences` class instead. ↓

fix Replace calls to crds.getreferences() with BestReferences context manager or direct instantiation.

gotcha CRDS requires internet access to fetch reference files unless you set up a local cache. Without cache, it downloads files on demand. ↓

fix Set the environment variable CRDS_PATH to a local directory to cache downloaded files. Use CRDS_SERVER_URL to specify a mirror.

gotcha When using BestReferences, the observation dictionary must include exact header keywords (case-sensitive). Missing keys cause KeyError. ↓

fix Always provide required keys: INSTRUMENT, DETECTOR, DATE-OBS, and any filter/grating/band specific to the instrument. Check instrument documentation.

Imports

crds
```
import crds
```
Main module. Submodules like crds.client, crds.core are imported as needed.
BestReferences
wrong
```
from crds.client import BestReferences
```
correct
```
from crds import BestReferences
```
BestReferences is imported from the top-level crds module, not from crds.client.

Quickstart

Basic usage: set server, create BestReferences with a context and observation parameters, then retrieve reference file mappings.

import crds
from crds import BestReferences

# Set server URL (optional, defaults to CRDS server)
crds.set_server_url(os.environ.get('CRDS_SERVER_URL', 'https://crdsserver.stsci.edu'))

# Get best references for an observation
context = 'jwst_ops.pmap'  # or use a specific context id
obs = {'INSTRUMENT': 'NIRCam', 'DETECTOR': 'NRCA1', 'FILTER': 'F090W', 'DATE-OBS': '2023-01-01'}
refs = BestReferences(context, obs)
print(refs.get_references())