Install & Compatibility
Where this runs
tested against v1.11.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.920 runs
installs and imports cleanly · install 0.0s · import 2.942s · 319.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 13.4s · import 2.938s · 310MB
321MB installed
● package 321MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Workflow
✓ from nipype.pipeline.engine import Workflow
Node
✓ from nipype.pipeline.engine import Node
Function
✓ from nipype.interfaces.utility import Function
IdentityInterface
✓ from nipype.interfaces.utility import IdentityInterface
FSLCommand
✓ from nipype.interfaces import fsl
✗ from nipype.interfaces.fsl import FSLCommand
Interfaces are typically accessed via the package (e.g., 'fsl') within 'nipype.interfaces' rather than direct import from submodules, which can change.
This quickstart demonstrates a basic Nipype workflow that takes two inputs, performs a simple multiplication using a custom Python function wrapped in a `Function` node, and executes the pipeline. Nipype workflows typically generate a working directory (`base_dir`) where intermediate and final results are stored. For complex workflows, consider `DataSink` or inspecting the cache for outputs.
import os
from nipype.pipeline.engine import Workflow, Node
from nipype.interfaces.utility import Function, IdentityInterface
def simple_multiply(a, b):
return a * b
# Create a workflow
wf = Workflow(name="simple_math_workflow")
wf.base_dir = os.environ.get('NIPYPE_WORKDIR', os.path.abspath('nipype_work_dir'))
# Input node to define initial data
inputnode = Node(IdentityInterface(fields=['val1', 'val2']), name='inputnode')
inputnode.inputs.val1 = 10
inputnode.inputs.val2 = 5
# Function node to perform multiplication
multiply_node = Node(Function(input_names=['a', 'b'],
output_names=['result'],
function=simple_multiply),
name='multiply_node')
# Connect the nodes
wf.connect(inputnode, 'val1', multiply_node, 'a')
wf.connect(inputnode, 'val2', multiply_node, 'b')
# Run the workflow
try:
print(f"Running workflow, output will be in {wf.base_dir}")
# Use 'MultiProc' plugin for local parallel execution
wf.run(plugin='MultiProc')
print("Workflow completed successfully. Check the base_dir for results.")
except Exception as e:
print(f"Workflow failed: {e}")
Debug
Known issues
breakingNipype interfaces *wrap* external neuroimaging software (e.g., FSL, SPM, AFNI, ANTS, FreeSurfer). These external tools must be installed and configured separately on your system; Nipype does not install them via pip. Incorrect or missing installations of these tools are a common source of errors.fixEnsure all required external neuroimaging software packages are installed, correctly configured (e.g., in your PATH environment variable), and compatible with your operating system and Nipype version.
affects: All versions
breakingVersion 1.8.4 pinned the `traits` dependency to `<6.4` to avoid breaking changes introduced in `traits` versions 6.4 and higher. Installing Nipype with a `traits` version >= 6.4 will likely lead to runtime errors.fixEnsure your `traits` package version is less than 6.4. If you have `traits >= 6.4`, downgrade it using `pip install 'traits<6.4'` before installing or after installing Nipype.
affects: <1.8.4 (if not pinned), >=1.8.4 (if traits updated beyond <6.4)
gotchaDefining `InputSpec` and `OutputSpec` for custom `Function` nodes or custom interfaces can be complex for new users. Incorrectly defined fields or types can lead to validation errors or unexpected workflow behavior.fixRefer to the Nipype documentation and examples for `InputSpec` and `OutputSpec` definitions. Pay close attention to field names, types (e.g., `File`, `traits.Bool`, `traits.Int`), and whether they are `mandatory`.
affects: All versions
breakingNipype versions require Python 3.10 or newer. Additionally, `numpy` 2.0+ support was explicitly added in version 1.9.1, and compatibility with `nibabel` 4.x/5+ and `networkx` 3+ was addressed in versions 1.8.3 and 1.8.6 respectively.fixUpgrade to Nipype 1.9.1 or newer for best compatibility with recent `numpy` versions. Ensure Python is 3.10+. If experiencing issues with `nibabel` or `networkx`, upgrade Nipype to 1.8.6 or newer.
affects: All versions before 1.9.1 for Numpy 2, before 1.8.6 for NiBabel 5/NetworkX 3, before 1.8.3 for NiBabel 4.
gotchaPrior to version 1.11.0, errors encountered when using the `run_without_submitting` execution mode (often used for debugging or testing single nodes) might not have been properly propagated, leading to silent failures or unclear diagnostics.fixUpgrade to Nipype 1.11.0 or newer for improved error propagation. When debugging, carefully inspect logs for any hidden exceptions, even in older versions.
affects: <1.11.0
gotchaNipype workflows generate extensive working directories (`base_dir`) for caching intermediate results. These directories can consume significant disk space and may contain many subfolders, making manual inspection challenging.fixSet `wf.base_dir` to a location with ample disk space. Utilize Nipype's logging and visualization tools (`graph.write_graph`) to understand workflow structure and execution. Manage disk space by deleting old `base_dir` contents when no longer needed.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nipype'
The Nipype library is either not installed in the current Python environment or the environment where it's installed is not activated.
fixEnsure Nipype is installed and the correct Python environment is active. If using `pip`: `pip install nipype`. If using `conda`: `conda install -c conda-forge nipype`.
TraitError: The 'fwhm' trait of an IsotropicSmoothInput instance must be a float, but a value of '4' <class 'str'> was specified.
A Nipype interface received an input with an incorrect data type; the 'Traits' system expects a specific type (e.g., float, int, file path) but received a different one.
fixEnsure that the input value matches the expected Python type (e.g., provide `4.0` for a float instead of `'4'`). Refer to the interface's documentation or use `interface.help()` to check expected input types.
RuntimeError: Command: slicetimer --in=... Standard error: Image Exception :: No image files match: ... Return code: -6 Interface SliceTiming failed to run.
A Nipype interface failed because the underlying external software command it wrapped (e.g., FSL's `slicetimer`) could not execute successfully, often due to issues like missing input files, incorrect file paths, or invalid command-line options.
fixCheck the 'Standard error' message for clues from the external software. Common fixes include ensuring input files exist at the specified (absolute) paths, that file permissions are correct, or that interface parameters are valid for the wrapped command. Running the command directly in the terminal might also help diagnose the issue.
OSError: command 'mri_convert' could not be found on host
Nipype could not find the executable for an external neuroimaging software command (e.g., FreeSurfer's `mri_convert`) in the system's PATH environment variable.
fixEnsure the necessary neuroimaging software (e.g., FreeSurfer, FSL, SPM) is installed and that its executable directory is correctly added to your system's PATH environment variable.
ModuleNotFoundError: No module named 'nipype.workflows.fmri'
Workflows that were previously part of the main `nipype` package have been moved to a separate package, `niflow-nipype1-workflows`, as of certain Nipype versions.
fixInstall the `niflow-nipype1-workflows` package: `pip install niflow-nipype1-workflows` or `conda install -c conda-forge niflow-nipype1-workflows`.
Upgrade
Version history
1.11.0latest on PyPI · released Mar 2, 2026
Audit
Dependencies
pythonrequiredNipype requires Python 3.10 or newer.
numpyrequiredCore dependency for scientific computing, support for NumPy 2.0+ was added in 1.9.1.
nibabelrequiredUsed for reading/writing neuroimaging data formats. Compatibility with NiBabel 5+ was added in 1.8.6.
traitsrequiredUsed for defining data structures and validating inputs. Specific version pinning is critical.
networkxrequiredUsed for workflow graph management. Compatibility with NetworkX 3+ was added in 1.8.6.