# The JWST calibration pipeline: turning raw telescope data into science products

> The jwst package is the calibration pipeline for the James Webb Space Telescope, maintained by STScI, which turns uncalibrated data from the imagers and spectrographs into standard science products. It runs on Linux and macOS, pins a wide set of astronomy dependencies, and needs a second step before it can run: setting up CRDS to fetch reference files.

**spacetelescope/jwst** — processing pipeline for James Webb Space Telescope imagery and spectroscopy

- Repository: https://github.com/spacetelescope/jwst
- Website: https://jwst-pipeline.readthedocs.io
- Stars: 665 · Forks: 194
- Language: Python
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/spacetelescope-jwst

## What the pipeline actually does to the data

The scope is stated in two sentences and it is a narrow one. The package jwst processes uncalibrated data from both imagers and spectrographs onboard the James Webb Space Telescope, an orbiting infrared observatory stationed at Earth-Sun L2, and the pipeline performs a series of calibration steps that result in standard data products usable for science. The word standard is doing real work in that sentence. The value of the pipeline is not that it can calibrate; it is that the calibration it performs is the one the instrument team defined, applied the same way to every dataset, so that two researchers reducing data from the same instrument get comparable results. Detailed explanations of specific calibration stages, reference files and pipeline builds are on the ReadTheDocs pages and on JDox. The repository is the Python package itself, with a jwst/ directory holding the code, docs/ for the documentation, changes/ for changelog fragments, and a test/ directory, plus pyproject.toml and setup.py at the root.

## Three ways to install, and the one you probably want

The install instructions assume an isolated environment, and the recommendation is explicit: we recommend using an isolated Python environment to install jwst, and environments can be managed with mamba, conda, virtualenv, uv, and so on. The worked example uses conda environments created with the mamba command, with a note to replace mamba with conda throughout if you prefer. You create an empty environment with Python installed, activate it, then install the package:

```shell
mamba create -n jwst_env python=3.13
```

```shell
mamba activate jwst_env
```

```shell
pip install jwst
```

Without a specified version, pip defaults to the latest released version that supports your environment, and to install a specific version you set it explicitly, for example pip install jwst==1.20.2, with a separate environment per version if you need to keep several. The third route is building from source, which the README marks as the latest unreleased and unstable development version, and it needs a C compiler:

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

That C compiler requirement is not incidental, and the setup.py file in the repository shows why. The package compiles a set of C extension modules, including jwst.lib.winclip, several cube_build modules for cube matching and blot median, and a straylight module, each built against the numpy headers with a NUMPY macro defined.

## Windows users are pointed at WSL

The platform note is short and it is a hard constraint. The JWST calibration pipeline currently supports Linux and macOS, and native Windows builds are not currently supported, with the instruction to use WSL instead. For a package that is normally run on a cluster or a workstation, that restriction is manageable, but it does mean the native Windows path is closed and that anyone following the ReadTheDocs install instructions on Windows has to read the WSL link rather than the instructions themselves. The repository classifiers agree: MacOS X and POSIX are listed, along with Python 3 only, and the requires-python field is >=3.12,<3.15 with classifiers for 3.12, 3.13 and 3.14. The Python floor is recent enough that an institutional machine on 3.11 will need an environment upgrade, and the fact that the install example uses python=3.13 suggests 3.13 is the version the operational work is tested against.

## CRDS is a mandatory step before the pipeline can run

The third numbered step in the quick start is not optional, and it is the part most likely to surprise someone who installs the package and immediately tries to run it. Before running the pipeline you must first set up your local machine to retrieve files from the Calibration Reference Data System, CRDS. The dependency list in pyproject.toml includes crds at a version range that excludes one specific release, 13.1.15, which is the kind of pin that comes from a real compatibility incident rather than a guess. The role CRDS plays is to supply the reference files, the calibration reference data, that the calibration steps apply. That is a network service and a local cache, so a first run downloads a substantial set of files, and a run on a machine without a working CRDS setup will fail before it produces anything. The README truncates at the point where it explains the CRDS setup, so the specifics of the crds config live in the documentation site rather than in this file.

## Reproducing the exact environment the instrument team used

The third installation option exists for a specific reason, and it is the option a validator or someone debugging a pipeline failure will want. There may be occasions where you need to replicate the exact environment used for canonical calibration operations by STScI, for example for validation testing or debugging issues, and the project packages releases for operations as environment snapshots that specify exact versions for both the pipeline and all dependencies. The README maps versions to operational builds, telling you for example to use jwst==1.17.1 for DMS build 11.2, and it points at a DMS Operational Build Versions table for the full correspondence. Since v1.16.1 the pipeline uses stasis to package environments and deliver releases, and the snapshot files differ per platform, so a macOS arm64 snapshot is a different artefact from a Linux one:

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

For anything older than 1.16.1 the README gives a different procedure, because the packaging tool changed, using mamba create with a conda_python file and then pip install against a requirements file. Both the version-to-build mapping and the pinned dependency sets are the reason a published result can be traced back to a specific operational environment.

## A wide dependency surface, pinned by hand

The dependency list in pyproject.toml tells you what the pipeline is built on and how carefully the versions are chosen. asdf handles the data model, astropy at 7.2 or later provides the astronomy core, numpy 2.0 or later, scipy, scikit-image, photutils for aperture photometry, gwcs for the generalized world coordinate system, synphot for synthetic photometry, tweakwcs for the world coordinate solution, and BayesicFitting. Three dependencies are unusual in a way worth understanding: stdatamodels, stcal and stpipe are not taken from PyPI at all but installed directly from their GitHub main branches, and the pyproject file shows the released version constraints commented out above each of them. That means a plain pip install of the pipeline pulls the current development head of those three packages rather than a published release, which is how a science pipeline tracks changes in its own calibration and data model libraries. The trade is deliberate and is worth knowing about before you try to pin your own environment, because you cannot pin those three to a fixed release and still get the intended behaviour.

## Where the pipeline is the wrong tool

Three limits are structural. The first is that this is a calibration pipeline, not a general data-reduction toolkit, and the sequence of calibration steps is the instrument team's, which means the reference file selection, the step parameters and the resulting products are defined for you. A researcher who needs a different processing path, a different background subtraction or a custom reference file is working against the tool rather than with it. The second is the version coupling to the data. Because the pipeline version has to match the DMS operational build that produced the data, running an old dataset with a current pipeline is not a neutral choice, and the README's own map between jwst versions and DMS builds is the reference for getting that right. The third is the licensing and platform surface. GitHub classifies the licence as Other, a custom licence the platform cannot map to a known identifier, with the full text in the LICENSE file, and the project is built by STScI under an AI_POLICY.md that sits next to the code, a signal that the project has an explicit position on how machine-generated contributions are handled. Add the Linux and macOS only restriction and you have a pipeline that fits the observatory's own workflows very well and fits everywhere else with some adaptation.

## Conclusion

jwst suits an astronomer who has JWST data and needs the standard calibration products rather than a bespoke reduction, and who can accept a pipeline whose reference files and step parameters are defined by the instrument team. It is the wrong tool if you need the source builds of a specific science program, if you want to control reference file selection yourself, or if you need a Windows-native install, since the pipeline supports Linux and macOS and points Windows users at WSL. Verify first which DMS build your data belongs to, because the README maps pipeline versions to operational builds and version 3.0.0 corresponds to DMS B13.0, and check the CRDS configuration before a large run, because the reference files are fetched from a network service and the README states you must set that up first.

## FAQ

### How do I install the JWST calibration pipeline?

Create an isolated environment, activate it, and install with pip install jwst, for example mamba create -n jwst_env python=3.13 followed by mamba activate jwst_env. The pipeline currently supports Linux and macOS, and native Windows builds are not supported, with WSL offered instead.

### What is CRDS and why do I need it before running the pipeline?

The Calibration Reference Data System supplies the reference files the calibration steps apply. The README states that before running the pipeline you must first set up your local machine to retrieve files from CRDS, and the crds package is a pinned dependency of jwst.

### How do I reproduce the environment STScI used for calibration operations?

Install the environment snapshot for the matching version, since the project packages releases for operations with exact versions for the pipeline and all dependencies. The README maps pipeline versions to DMS operational builds, for example jwst==1.17.1 for DMS build 11.2, and notes that macOS and Linux need different snapshot files.

### Which Python versions does the jwst package support?

The pyproject file declares requires-python of >=3.12,<3.15, with classifiers for Python 3.12, 3.13 and 3.14, and the install instructions create the environment with python=3.13.

### Does the pipeline need a C compiler?

Yes, to build it from source. The README marks the source install with a note that you need a C compiler, and setup.py compiles C extension modules such as jwst.lib.winclip and several cube_build modules against the numpy headers.

## Sources

- [Issues](https://github.com/spacetelescope/jwst/issues)
- [Project website](https://jwst-pipeline.readthedocs.io)
- [README](https://github.com/spacetelescope/jwst/blob/main/README.md)
- [Releases](https://github.com/spacetelescope/jwst/releases)
- [spacetelescope/jwst on GitHub](https://github.com/spacetelescope/jwst)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/spacetelescope-jwst