Rasterio 1.5 is a minor release that raised the Python floor by three versions

A minor version raised the Python floor by three and NumPy by a major

One sentence in the introduction carries the whole compatibility story, and it is scoped to a version. Rasterio 1.5 and later work with Python 3.12 and newer, NumPy 2 and newer, and GDAL 3.8 and newer, with official binary packages for the three desktop systems carrying most built in format drivers plus three named add on libraries. So a 1.5 release dropped every Python from 3.9 through 3.11 and the entire NumPy 1 series. The package metadata agrees, requiring 3.12 and newer, depending on NumPy 2 and newer, and declaring classifiers for three Python versions only. That is a considerable amount of breakage delivered in a minor version rather than a major one, and it is stated plainly rather than buried, which is the most anyone can ask, but a project that pins to the second digit of its own version should not also be upgrading its interpreter's major version under a minor tag.

The declared floor for the command line library is version four

One dependency in the runtime list has a floor that cannot be right. It declares the command line library at version four and above, excluding a specific eight point two series, with a comment and a link to a specific upstream issue explaining why that series is excluded. Excluding a series is sensible when the bug is in it. Setting the floor four major versions back is not, and the consequence is that the declared range admits a command line library from years ago, which no longer has the interface this code calls. The test requirements file for the same project pins the same dependency to the eight point zero compatible range with the same exclusion. So there are two constraints for one dependency, one of which is a floor nobody wants and the other of which is what actually runs.

The build dependency table is duplicated and the project admits it

The build configuration lists its compiler, its array library, and its build backend in one table. There is a second table for the build dependency group, and it is not identical: the Cython range is narrower in the second table than in the first, while the array library and the build backend match. Above the first table is a comment naming the second table and saying that when you update one you must update the other. So the project has documented its own duplication hazard instead of removing it, which is better than not noticing and considerably worse than a single source. The build script goes further in the other direction. It does not treat Cython as optional: the import is wrapped in a guard that raises a specific error and exits if the compiler front end is missing, with a message saying it is required to build the library.

Three ways to find the geospatial library, written out at the top of the build script

The imperative build script opens with a comment block that is the best documentation in the repository, because it names the three mechanisms and their priority order. One environment variable gives the path to a configuration program that points at the headers, the libraries, and the data files. A second, when set, causes the data files to be copied into the source or binary distribution, and the comment says this is essential when producing self-contained wheels. A third is the ordinary search path: if the configuration program is not found, the script looks for the information executable instead, runs it to get the version, and computes the include, library, and share directories from that executable's own location. The script also carries explicit flags for distinguishing two major generations of the underlying library and a four-slot output list, so the branching is visible rather than inferred.

The inspector example still reports version zero and a Python from 2016

The command line section introduces an inspector subcommand that opens any raster so you can look around it with Python, which is the fastest way to understand an unfamiliar file. The transcript underneath it begins with a version banner naming release zero point ten, running on Python three point four point one. The current release is one point five point two and the floor is Python three point twelve. So the flagship example in the readme is a decade old, and it is the one piece of documentation every new user is most likely to run first and copy from. The rest of the transcript is honest about what it is doing: it prints a name, a shape, a coordinate reference system as a dictionary, and then dumps a masked array whose mask is entirely true, which is itself a useful thing to see once.

The issue tracker is reserved and questions go to a mailing list

The support section is short and unusually firm. The primary forum for questions about installation and usage is a mailing list, and the text says the authors and other users will answer when they have expertise to share and time to explain, asking people to craft a clear question and be patient. Then the second paragraph: please do not bring these questions to the issue tracker, which the project wants to reserve for bug reports and other actionable issues. That is a legitimate and common policy. It is also a slow one for anything urgent, and the phrasing about having time is an honest signal that this is a volunteer project. The repository root backs the posture up with a security policy, a code of conduct, a governance document, a design document, and a citation file.

The project began at a company and was donated four years ago

The authors section is one sentence and it explains a lot about the project. It was begun at a mapping company and transferred to its own GitHub organisation in October 2021. What followed is the shape you would expect from a corporate origin with a nonprofit home: a governance document, a code of conduct, a security policy, a change log, an authors file, a design document, a separate contribution guide written in reStructuredText, and a pre-commit configuration. There is also a blame-ignore file, which lists commits excluded from authorship attribution, so history rewriting is on the record rather than hidden. The build system reflects the same layering, with a declarative project file for installation and a separate imperative script that carries all the discovery logic.

Editorial conclusion

rasterio is the right answer if you want raster data as NumPy arrays rather than as a handle to a C library, and the window and profile model is the part worth learning because it survives the rest. Check four things. Which Python you have, because the current line needs 3.12 or newer and the older releases will not satisfy it. Whether you want a wheel or a source build, because the wheel route hides a compiler, a Cython toolchain, and a GDAL discovery step that the source route puts in front of you. Which command line library you want, because the inspector subcommand is the fastest way to look at a file and the plugins are what you would use if you were adding your own. And how you ask questions, because the project reserves its issue tracker for actionable bugs and answers usage questions on a mailing list when maintainers have time, which is a fair policy and a slow one.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. rasterio/rasterio on GitHub
4. README
5. Releases