Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
PyRadiomics is an open-source Python package that extracts quantitative radiomic features (shape, intensity and texture measurements) from a medical image and a segmentation mask of a region of interest. This guide is for lab and computational researchers who need to install it, run it from the command line or Python, set the parameters that decide whether results are reproducible, and read the output table. Facts below come from the PyRadiomics documentation and PyPI page, read 2026-11-11.
What PyRadiomics is used for in research
PyRadiomics takes two inputs for each case, an image and a mask labelling the region of interest, and returns a set of numeric features computed inside that region. The feature families are First Order (19 features), Shape 3D (16), Shape 2D (10), GLCM (24), GLRLM (16), GLSZM (16), NGTDM (5) and GLDM (14). Most definitions follow those of the Image Biomarker Standardisation Initiative (IBSI), and the feature documentation notes each place where PyRadiomics differs. Examples noted there: First Order features apply no correction for negative gray values, the IBSI definition uses excess kurtosis (corrected by -3), which is a stated difference, and Total Energy is not present in the IBSI definitions.
The package is released under the BSD 3-Clause licence. The citation requested by the project is van Griethuysen JJM et al. (2017), “Computational Radiomics System to Decode the Radiographic Phenotype”, Cancer Research 77(21):e104-e107, doi:10.1158/0008-5472.CAN-17-0339. If you analyse images with it, cite the paper and the version you ran; see research software and citation and FORCE11 Software Citation Principles. Input images typically come from clinical archives; the DICOM standard and viewers guide covers the header and format side, and medical imaging research areas gives the wider field.
How to install or access it
As of the PyPI page read on 2026-11-11, the latest release is 3.1.0 (17 May 2023), described as compatible with Python 3.5 or later, with prebuilt wheels only for CPython 3.7, 3.8 and 3.9. On other Python versions pip has to build from source, which needs git and a C compiler. Pick the route that fits your environment.
| Route | Command or step (from the official documentation) | When it fits |
|---|---|---|
| pip | python -m pip install pyradiomics |
Python 3.7-3.9, where prebuilt wheels exist |
| conda | conda install -c radiomics pyradiomics |
You already manage environments with conda (see sharing a reproducible conda environment) |
| From source | git clone git://github.com/Radiomics/pyradiomics, then cd pyradiomics, python -m pip install -r requirements.txt, python setup.py install. For an in-place build: python setup.py build_ext --inplace |
Python versions without a wheel; needs git and a C compiler |
| Docker | docker pull radiomics/pyradiomics:CLI, then docker run radiomics/pyradiomics:CLI --help. Mount data with -v <HOST_DIR>:<CONTAINER_DIR> |
You want the command-line tool without managing a Python build (see Docker vs virtual machine) |
| 3D Slicer | Install the Radiomics extension through the Extension Manager | You prefer a graphical interface |
The installation page itself still lists Python 3.5-3.7 for wheels, which is older than the PyPI file list; check the PyPI “Download files” tab for the wheel that matches your interpreter.
Step-by-step: extract features from one image and mask
- Prepare inputs. You need an image file and a mask file readable by the package, covering the same physical space. Use the same label value in the mask for the region you want (the default label is 1).
- Check the CLI is installed. Run
pyradiomics -h. - Extract for a single case. Run
pyradiomics <image> <mask>. By default the result prints to the console. - Save to a file. Add
-o results.csv -f csv. - Process many cases. Make a CSV with columns named exactly
ImageandMask(case-sensitive); optional columns areLabelandLabel_channel. Any other columns are copied into the output. Then runpyradiomics <input.csv> -o results.csv -f csv, adding--jobs <N>to run in parallel. - Apply a settings file. Pass
--param <file>, where the file is YAML (example below). Individual overrides can be given with the repeatable--settingoption. - Control logging. Use
--verbosity,--log-file <FILE>and--logging-level; by default messages at WARNING level and above are shown.
The same extraction in Python
from radiomics import featureextractor, getTestCase
extractor = featureextractor.RadiomicsFeatureExtractor(params) # params: path to YAML file
result = extractor.execute(imageName, maskName)
Passing voxelBased=True to execute returns SimpleITK images (one map per feature) in addition to the diagnostics. getTestCase fetches the project’s sample data, which is useful for a first test.
Voxel-based extraction from the command line
Add --mode voxel and an output directory with --out-dir <DIR>. Each feature is then written as a NRRD map named Case-<idx>_<FeatureName>.nrrd, and the tabular output still carries the diagnostics.
Settings that decide whether your results are reproducible
Radiomic values depend on how the image is discretised, resampled and filtered, so record the settings with the results. The customization documentation gives these defaults and options:
| Setting | Default | What it controls |
|---|---|---|
binWidth |
25 | Width of gray-level bins for texture features; binCount is the alternative |
resampledPixelSpacing |
None | Resampling target, a list of three floats; 0 keeps the original spacing on that axis |
label |
1 | Which mask value defines the region of interest |
normalize |
False | Whether image intensities are normalised before extraction |
| Image types | Original only | Also available: Wavelet, LoG, Square, SquareRoot, Logarithm, Exponential, Gradient, LocalBinaryPattern2D and LocalBinaryPattern3D |
A parameter file combining these looks like this (structure taken from the documentation’s example):
imageType:
Original: {}
LoG:
sigma: [1.0, 3.0]
Wavelet:
binWidth: 10
featureClass:
glcm:
firstorder: ['Mean', 'StandardDeviation']
shape: [Volume, SurfaceArea]
setting:
binWidth: 25
resampledPixelSpacing:
label: 1
Keep this file with your analysis code and report it in the methods section. Computational reproducibility depends on it as much as on the software version.
Output and how to read it
Each row is one case (CSV mode) and each feature column is named <filter>_<class>_<feature>, for example original_firstorder_Mean for the First Order mean on the unfiltered image. Alongside the features, the output includes diagnostics columns that accompany the feature values and help trace a result to its configuration. Columns you added to the input CSV are carried through, which lets you keep patient or sample identifiers beside the numbers (handle these under your data-governance rules).
Shape features are calculated on the original image and mask only, not on filtered images, and are independent of gray values. Shape 2D requires a truly 2D mask: set force2D and make sure the out-of-plane dimension has size 1. Where the documentation marks a feature as deprecated because it duplicates another (for example Homogeneity 1, equal to Inverse Difference), use the retained feature. When you compare values with another radiomics tool, check the IBSI differences listed in the feature documentation first.
Troubleshooting
- Image and mask do not align. The customization documentation describes
geometryTolerance(when unset, SimpleITK’s default tolerance of 1e-16 applies) andcorrectMask. WithcorrectMaskset to True, the mask is resampled to the image using nearest-neighbour interpolation. It still fails if the region of interest lies outside the physical space of the image. - No wheel for your Python version. Build from source (git and a C compiler required), use the Docker CLI image, or create an environment on Python 3.7-3.9.
- Batch file not read. Check that the header names are exactly
ImageandMask, with that capitalisation. - Need more detail. Raise logging with
--verbosityand write to--log-file.
Free alternatives: other ways to run it, and a benchmark for any tool
PyRadiomics is itself free. The routes below are the free options the project documents for running it without writing Python; for a different tool altogether, the IBSI provides reference values that any implementation can be checked against.
| Option | What it is | Source |
|---|---|---|
| 3D Slicer Radiomics extension | Graphical interface installed via the Extension Manager | PyRadiomics installation documentation |
| Docker CLI image | Command-line tool in a container, no local build | PyRadiomics installation documentation |
| IBSI reference values | Community standard with reference values for 169 commonly used radiomic features (IBSI 1, completed March 2020) and, in IBSI 2 (completed February 2024), commonly used filters such as wavelets and Laplacian of Gaussian; use it to check any radiomics implementation | theibsi.github.io |
FAQ
What is PyRadiomics?
An open-source Python package, BSD 3-Clause licensed, that extracts radiomic features from a medical image and a region-of-interest mask.
How do I install PyRadiomics?
Run python -m pip install pyradiomics, or conda install -c radiomics pyradiomics. Prebuilt PyPI wheels exist for CPython 3.7, 3.8 and 3.9; other versions build from source.
Which version is current?
PyPI lists 3.1.0, released 17 May 2023, as the latest release as of 2026-11-11.
How do I run it on many cases?
Provide a CSV with Image and Mask columns and run pyradiomics input.csv -o results.csv -f csv, optionally with --jobs.
Does it follow the IBSI?
Most features follow IBSI definitions; the feature documentation notes where they differ.
Sources
- PyRadiomics documentation: Installation, Usage, Radiomic Features, Customization (read 2026-11-11)
- PyRadiomics on PyPI (read 2026-11-11)
- van Griethuysen JJM et al. (2017) Cancer Research 77(21):e104-e107, doi:10.1158/0008-5472.CAN-17-0339
- Image Biomarker Standardisation Initiative (read 2026-11-11)







