Spectral Python: a pure Python core for hyperspectral cubes

A hyperspectral image is a stack of spectra, not a picture

Spectral Python exists for data that ordinary image libraries cannot represent. A hyperspectral image, also called imaging spectroscopy data, records a spectrum for every pixel, so the file is a three dimensional cube of measurements rather than a grid of colours. Working on it means reading vendor specific formats, resampling bands, applying transformations across the wavelength axis, and pulling out targets or anomalies. The project describes itself as a pure Python module with functions for reading, displaying, manipulating and classifying hyperspectral imagery, and the repository topics place it squarely in remote sensing: anomaly-detection, hyperspectral-image-classification, target-detection and visualization. The user is therefore a remote sensing researcher, a graduate student writing a thesis pipeline, or an engineer in a lab that owns an imaging spectrometer. The small audience is the point. The library has a decades-old vocabulary of band math and classification helpers rather than a general-purpose data API.

The package is split into algorithms, io, graphics and a spectral database

The distribution lists its subpackages explicitly in setup.py:

      packages=['spectral', 'spectral.algorithms', 'spectral.database',
                'spectral.graphics', 'spectral.io', 'spectral.tests',
                'spectral.utilities'],

That list is a compact map of the library. spectral.io is where file reading and writing live, spectral.algorithms holds the processing routines, spectral.graphics covers the display side, and spectral.database is a separate module for working with spectral libraries rather than with image cubes. spectral.utilities and spectral.tests round it out. The separation matters in practice because it tells you where to look when something fails, and it explains why the install is not always all you need: the graphics side carries optional dependencies, so a machine that never opens a plot can still run the algorithms. The version string is not hardcoded in setup.py. It is parsed out of spectral/__init__.py at build time with a regular expression, a small detail that means the source tree is the single place a version is defined. Author attribution in setup.py goes to Thomas Boggs, and the licence is MIT.

Three installation routes, and the one that needs no installation at all

The latest release is always hosted on PyPI, so the normal route is a single pip command:

    pip install spectral

If you would rather work from a downloaded archive, the same guidance applies to the zip or tarball releases, which are published on PyPI and on the GitHub releases page and installed with:

    python setup.py install

The third route is the one experienced contributors use. You clone the git repository and install as above, but the README notes that no explicit installation is required at all: you can simply access or symlink the spectral module inside the source tree. That is convenient for hacking on the algorithms and awkward for anything else, since nothing is registered with the interpreter. A fourth path exists for conda users, and the README points at the official conda-forge documentation for up-to-date guidance on installing SPy that way. The default branch of the repository is develop, so a clone gives you the development line rather than the last tagged release, which is one more reason to install from PyPI if you want reproducible numbers.

Missing optional dependencies turn test failures into silent skips

The unit test suite is the most instructive part of the README, because it explains how the library behaves when its optional pieces are absent. Tests for a given package are skipped automatically if that package is not installed, and you can pass --require-optional-deps to turn a missing optional dependency into a hard failure instead of a skip. The graphics and GUI functionality is covered by tests marked graphics, with 3D window tests marked gui3d, and the 2D display path uses matplotlib and Pillow while the 3D display path uses PySide6 and PyOpenGL. To run only the algorithmic and input and output tests, excluding all graphics and GUI cases:

    pytest -m "not graphics" spectral/tests

To force the 2D rendering tests to run and fail rather than skip when a package is missing:

    pytest --require-optional-deps=matplotlib,PIL spectral/tests

For a headless machine, the 3D tests need a real OpenGL rendering surface, and the README shows how to run the full set under a virtual one:

    xvfb-run -a pytest --require-optional-deps=all spectral/tests

This is good practice that many scientific packages lack, and it is also a trap in CI. A pipeline that treats a green run as proof that rendering works will quietly pass on a machine with no graphics stack at all.

The test suite needs sample data files you have to fetch yourself

Before the tests will pass, the sample data files have to be downloaded to the current directory, or to a directory named by the SPECTRAL_DATA environment variable. numpy and pytest are also required. Nothing in the repository ships the imagery itself, which makes sense for gigabyte-scale spectra but means a fresh clone fails its own suite until you have populated a data directory by hand. The data does exist inside the package for some cases: setup.py declares package_data for spectral.tests with data/*.spc files, txt files under data/ecostress, the data/relab data tree, and the data/usgs ASCII library data. So the repository carries a slice of the fixtures while the documentation still asks you to download the rest, and the difference between those two sets is worth understanding before you spend an afternoon wondering why a test cannot find its file. The version history in VERSIONS.txt and the MANIFEST.in file sit alongside this machinery, and the top level of the tree is otherwise small: setup.py, the spectral/ package, a .travis.yml and a .github/ directory.

Release gaps of two and three years sit inside an MIT licensed project

Version 0.25 was released on 2026-07-25, version 0.24 on 2025-04-13, and version 0.23.1 on 2022-10-02. Read that sequence carefully. Between 0.23.1 and 0.24 there is a gap of more than two years, and the gap between 0.24 and 0.25 is about a year. The last push to the default branch was on 2026-09-04, so the code is still moving even though the tags arrive irregularly, and the project is not archived. What this means for an adopter is that there is no nightly, no long-term support branch and no semantic versioning scheme to rely on. Versions below 1.0 also mean the usual expectation that interfaces may change between minor releases. The licence is MIT, which is permissive and poses no obstacle to commercial or closed-source use of the code, though the MIT terms still require the copyright notice and licence text to travel with the software. The project is hosted with a general home page at spectralpython.net and no separate project homepage is listed.

Against a hand-rolled NumPy pipeline, SPy trades speed for scope

The honest alternative is not another library but your own code, because the alternative to a toolbox is usually a script you write yourself. A pure NumPy pipeline can load a cube if you add a reader, can do band arithmetic in a handful of lines, and will usually be faster on large arrays, since the per-band loops in a pure Python library become the bottleneck once you start stacking thousands of scenes. What you give up is everything else: the file format handling in spectral.io, the display routines in spectral.graphics, the classification helpers in spectral.algorithms, and the spectral library access in spectral.database, none of which you would want to reimplement and all of which are quietly expensive to get right. The trade is therefore about scope and review time, not raw throughput. For a thesis, a class exercise or an analysis you will revisit in six months, the readable library is usually the better bet. For a production pipeline processing a full survey archive on a schedule, the pure Python core is the wrong layer, and the sensible arrangement is to use SPy for exploration and for the awkward file formats, then move the hot loops to array code.

Editorial conclusion

Spectral Python is worth adopting for research and teaching code that has to stay readable, reproducible and easy to install on a student laptop, and for teams that already work with imaging spectroscopy data and want the file handling, display and classification routines in one place. It is the wrong choice for pipelines where a cube has to be processed at interactive speed on a workstation, since the package is pure Python and the project documents no GPU or parallel execution path, and it is the wrong choice if you need a maintained stream of new file formats. Before depending on it, pin an exact version, since release 0.24 sat in place from 2025-04-13 until 0.25 arrived on 2026-07-25, check that the optional graphics stack you need is present because those tests silently skip when a package is missing, and download the sample data files that the test suite expects in the current directory or at the path named by the SPECTRAL_DATA environment variable.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. spectralpython/spectral on GitHub