Install & Compatibility
Where this runs
tested against v0.27.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.7s · import 0.271s · 94MB
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
rawpy.enhance
✓ import rawpy.enhance
For advanced features like bad pixel detection and repair.
This quickstart demonstrates how to load a RAW image, postprocess it using default settings, and save the resulting RGB image as a TIFF file. It also shows an example of saving a 16-bit linear image. It uses `imageio` for saving the output, which needs to be installed separately. The code includes basic error handling for unsupported RAW files and uses a dummy file for execution without requiring an actual RAW image upfront.
import rawpy
import imageio.v3 as iio
import os
# Create a dummy RAW file for demonstration (replace with your .CR2, .NEF, etc.)
# In a real scenario, you would have an actual RAW image file.
dummy_raw_content = b'\x00' * 1024 # Not a real RAW, but allows the code to run without file not found
dummy_raw_filename = 'dummy.nef'
with open(dummy_raw_filename, 'wb') as f:
f.write(dummy_raw_content)
path = dummy_raw_filename
try:
# Load a RAW file using the context manager for resource safety
with rawpy.imread(path) as raw:
# Postprocess the RAW image to an RGB NumPy array
# Uses default parameters for demosaicing, white balance, etc.
rgb = raw.postprocess()
# Save the postprocessed image using imageio (requires 'imageio' installed)
output_filename = 'default.tiff'
iio.imwrite(output_filename, rgb)
print(f"Image saved to {output_filename}")
# Example: Save as 16-bit linear image
rgb_16bit = raw.postprocess(gamma=(1,1), no_auto_bright=True, output_bps=16)
output_filename_16bit = 'linear.tiff'
iio.imwrite(output_filename_16bit, rgb_16bit)
print(f"16-bit linear image saved to {output_filename_16bit}")
except rawpy.LibRawFileUnsupportedError:
print(f"Error: '{path}' is not a supported RAW file format, or it's corrupted/incomplete.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
# Clean up dummy file
if os.path.exists(dummy_raw_filename):
os.remove(dummy_raw_filename)
Debug
Known issues
breakingmacOS Intel support was removed in v0.26.0. Users on macOS with Intel CPUs will not be able to install or use rawpy versions 0.26.0 and later.fixUse rawpy v0.25.x or earlier on macOS Intel, or migrate to a different architecture (e.g., Apple Silicon) or operating system.
affects: >=0.26.0
breakingAs of v0.23.0, rawpy will now raise an error for corrupt or malformed RAW files instead of silently returning garbage data. This improves robustness but may require updating existing code that implicitly handled such cases.fixImplement explicit try-except blocks (e.g., for `rawpy.LibRawError` or `rawpy.LibRawFileUnsupportedError`) around file opening and processing to handle corrupted or unsupported RAW files gracefully.
affects: >=0.23.0
breakingPython 3.8 support was dropped in v0.22.0. Users on Python 3.8 must upgrade their Python version to continue using recent rawpy releases.fixUpgrade to Python 3.9 or newer.
affects: >=0.22.0
breakingNumpy 2.x support was added in v0.22.0, but older numpy versions are no longer supported. Ensure your numpy installation is compatible with rawpy.fixUpgrade numpy to a compatible version (e.g., `pip install --upgrade numpy`). Check rawpy's documentation for specific minimum numpy versions for your Python version.
affects: >=0.22.0
gotchaOn Linux, `rawpy` requires the `LibRaw` library to be installed system-wide. Binary wheels for `rawpy` do not bundle `LibRaw` on Linux. Installation instructions for `LibRaw` vary by distribution.fixInstall `libraw-dev` (or equivalent) via your system's package manager (e.g., `sudo apt-get install libraw-dev` on Ubuntu) or compile `LibRaw` from source before installing `rawpy`.
affects: All versions on Linux
gotchaAttempting to open a non-RAW file, a corrupted file, or a RAW file with an unsupported format/camera model will raise a `rawpy.LibRawFileUnsupportedError`.fixVerify the input file is a genuine, uncorrupted RAW image from a supported camera model. Use a `try-except` block to catch `rawpy.LibRawFileUnsupportedError` and handle unsupported files gracefully.
affects: All versions
gotchaWhen using Python's `multiprocessing` module on Linux, deadlocks can occur due to an interaction between OpenMP (used in rawpy's Linux wheels) and the default `fork` start method.fixChange the multiprocessing start method to 'spawn' or 'forkserver' (e.g., `multiprocessing.set_start_method('spawn')`) before creating any `multiprocessing.Process` objects or pools. affects: All versions on Linux
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'rawpy'
The 'rawpy' package is not installed in your current Python environment.
fixInstall the library using pip: `pip install rawpy`
rawpy.LibRawError: Cannot open file 'path/to/your/image.NEF'
The specified RAW file path is incorrect, the file does not exist, or there are insufficient read permissions.
fixVerify that the file path is correct, the file exists, and you have read access to it. Check for typos in the path.
rawpy.LibRawError: Unsupported file format or file is corrupted
The input file is not a valid RAW image format supported by LibRaw, or the file itself is corrupted.
fixEnsure the input file is a legitimate RAW image from a camera supported by LibRaw. Try opening a different RAW file to confirm the issue is not with the file itself.
AttributeError: 'RawPy' object has no attribute 'image'
You are attempting to access an attribute named 'image' which does not exist on the `RawPy` object. The correct attributes for image data are `raw_image` (for unprocessed data) or `postprocessed_image` (for processed RGB data).
fixUse `raw.raw_image` to get the unprocessed raw data or `raw.postprocessed_image` after calling `raw.postprocess()` to get the decoded RGB image data, e.g., `rgb = raw.postprocess()`, then `rgb_array = raw.postprocessed_image`.
Upgrade
Version history
0.27.0latest on PyPI · released May 7, 2026
Audit
Dependencies
numpyrequiredCore dependency for array operations and image data representation.
imageiooptionalCommonly used for saving processed images, as shown in quickstart examples.