Skip to main content
v2026.11,986 entries · CC-BY 4.0

PyRadiomics: Install, Extract Features, Read Output

PyRadiomics install routes, the CLI and Python commands for radiomic feature extraction, the settings that affect reproducibility, and how to read the output.

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

  1. 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).
  2. Check the CLI is installed. Run pyradiomics -h.
  3. Extract for a single case. Run pyradiomics <image> <mask>. By default the result prints to the console.
  4. Save to a file. Add -o results.csv -f csv.
  5. Process many cases. Make a CSV with columns named exactly Image and Mask (case-sensitive); optional columns are Label and Label_channel. Any other columns are copied into the output. Then run pyradiomics <input.csv> -o results.csv -f csv, adding --jobs <N> to run in parallel.
  6. Apply a settings file. Pass --param <file>, where the file is YAML (example below). Individual overrides can be given with the repeatable --setting option.
  7. 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) and correctMask. With correctMask set 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 Image and Mask, with that capitalisation.
  • Need more detail. Raise logging with --verbosity and 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

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about PyRadiomics: Install, Extract Features, Read Output

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →