James Webb Space Telescope Calibration Pipeline

This package (jwst) processes uncalibrated data from both imagers and spectrographs onboard the James Webb Space Telescope (JWST), an orbiting infrared observatory stationed at Earth-Sun L<sub>2</sub>. The pipeline performs a series of calibration steps that result in standard data products usable for science.

Detailed explanations of specific calibration stages, reference files, and pipeline builds can be found on the ReadTheDocs pages and JDox.

[!NOTE] If you have trouble installing this package, have encountered a bug while running the pipeline, or wish to request a new feature, please open an issue on GitHub or contact the JWST Help Desk.

Quick Start
Code Contributions
DMS Operational Build Versions

Quick Start

1. Install the Pipeline

[!IMPORTANT] The JWST calibration pipeline currently supports Linux and macOS. Native Windows builds are not currently supported; use WSL instead.

We recommend using an isolated Python environment to install jwst. Python "environments" are isolated Python installations, confined to a single directory, where you can install packages, dependencies, and tools without cluttering your system Python libraries. You can manage environments with mamba / conda, virtualenv, uv, etc.

These instructions assume you are creating Conda environments with the mamba command (see Miniforge for installation instructions); to use conda instead, simply replace mamba with conda in the following commands.

First, create an empty environment with Python installed:

mamba create -n jwst_env python=3.13

Then, activate that environment (necessary to be able to access this isolated Python installation):

mamba activate jwst_env

Finally, install jwst into the environment:

pip install jwst

Without a specified version, pip defaults to the latest released version that supports your environment. To install a specific version of jwst, explicitly set that version in your pip install command:

pip install jwst==1.20.2

To install a different version of jwst, simply create a new environment for that version:

mamba create -n jwst1.20_env python=3.13
mamba activate jwst1.20_env
pip install jwst==1.20

mamba create -n jwst1.19_env python=3.12
mamba activate jwst1.19_env
pip install jwst==1.19

Option: Build Pipeline Directly from Source Code

[!IMPORTANT] You need a C compiler to build the JWST calibration pipeline (and dependencies) from source.

To install the latest unreleased (and unstable) development version directly from the source code on GitHub:

pip install git+https://github.com/spacetelescope/jwst

Option: Install Exact Operational Environment

There may be occasions where you need to replicate the exact environment used for canonical calibration operations by STScI (e.g. for validation testing or debugging issues). We package releases for operations as environment snapshots that specify exact versions for both the pipeline and all dependencies.

See the DMS Operational Build Versions table for the version of the pipeline corresponding to each operational build. For example, use jwst==1.17.1 for DMS build 11.2. Also note that Linux and macOS systems require different snapshot files:

mamba env create --file https://ssb.stsci.edu/stasis/releases/jwst/JWSTDP-1.18.1/delivery/latest-py312-macos-arm64.yml
mamba activate JWSTDP-1.18.1-1-py312-macos-arm64

[!NOTE] Starting with jwst==1.16.1, the JWST pipeline uses stasis to package environments and deliver releases. If you need a version of jwst prior to 1.16.1, use a slightly different procedure:
mamba create -n jwstdp-1.16.0 --file https://ssb.stsci.edu/releases/jwstdp/1.16.0/conda_python_macos-stable-deps.txt
mamba activate jwstdp-1.16.0
pip install -r https://ssb.stsci.edu/releases/jwstdp/1.16.0/reqs_macos-stable-deps.txt

2. Set up the Calibration Reference Data System (CRDS)

Before running the pipeline, you must first set up your local machine to retrieve files from the Calibration Reference Data System (CRDS) CRDS provides calibration reference files for several telescopes, including JWST.

Set CRDS_SERVER_URL and CRDS_PATH to run the pipeline with access to reference files from CRDS:

export CRDS_SERVER_URL=https://jwst-crds.stsci.edu
export CRDS_PATH=$HOME/data/crds_cache/

[!NOTE] The CRDS PUB Server (https://jwst-crds-pub.stsci.edu) was decommissioned in March 2023. To use historical files from the PUB server, contact the JWST Help Desk.

The pipeline will automatically download individual reference files and cache them in the CRDS_PATH directory. Expect to use 50 gigabytes (or more) of disk space for reference files, depending on the instrument modes in use.

[!TIP] Users within the STScI network do not need to set CRDS_PATH (it defaults to shared network storage).

To use a specific CRDS context other than that automatically associated with a given pipeline version, explicitly set the CRDS_CONTEXT environment variable:

export CRDS_CONTEXT=jwst_1179.pmap

For more information, see the docs page on JWST CRDS reference files.

3. Run the Pipeline

Once installed, the pipeline allows users to run and configure calibration themselves for custom processing of JWST data, either from the command line with strun or from Python with pipeline and step functions and classes in the jwst package (see this curated set of Jupyter notebooks for example usage). Additionally, the jwst package provides JWST datamodel classes, the recommended method for reading and writing JWST data files in Python.

Code Contributions

jwst is an open source package written in Python. The source code is available on GitHub. New contributions and contributors are very welcome! Please read CONTRIBUTING.md, the public API definition, and the public API deprecation policy

We strive to provide a welcoming community by abiding with our CODE_OF_CONDUCT.md.

See [TESTING.md](./TESTING.md

Jwst

Install / Use

README