pybids

library0.22.0pypypi✓ verified 87d ago

PyBIDS is a Python library that provides an interface for interacting with datasets organized according to the Brain Imaging Data Structure (BIDS) specification. It allows users to query, manage, and extract information from BIDS datasets, supporting local and cloud-based paths. The current version is 0.22.0, and the library maintains an active release cadence with minor feature releases every few months and frequent bug-fix updates.

data ai-ml

pip install pybids

github ↗package ↗

INSTALL

IMPORT

SIG · PYBIDS

pybids

datapythonv0.22.0

Install

16.9s avg

Import

1073ms

Disk

363MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.22.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

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 1.116s · 361.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 16.9s · import 1.029s · 348MB

363MB installed

● package 363MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BIDSLayout

✓ from bids import BIDSLayout

✗ from pybids.layout import BIDSLayout

The top-level `bids` package is the correct entry point, not a submodule of `pybids`.

BIDSLayoutIndexer

✓ from bids.layout import BIDSLayoutIndexer

✗ from bids import BIDSLayoutIndexer

While `BIDSLayout` is top-level, `BIDSLayoutIndexer` is explicitly in `bids.layout`.

This quickstart demonstrates how to initialize a `BIDSLayout` for a BIDS-compliant dataset and query for specific files using entity key-value pairs. It includes creating a minimal dummy BIDS structure to make the example runnable without an existing dataset.

import os from bids import BIDSLayout # Create a dummy BIDS directory for demonstration dummy_bids_dir = 'my_bids_dataset' os.makedirs(os.path.join(dummy_bids_dir, 'sub-01', 'ses-01', 'anat'), exist_ok=True) with open(os.path.join(dummy_bids_dir, 'dataset_description.json'), 'w') as f: f.write('{"Name": "My Dummy Dataset", "BIDSVersion": "1.4.0"}') with open(os.path.join(dummy_bids_dir, 'sub-01', 'ses-01', 'anat', 'sub-01_ses-01_T1w.nii.gz'), 'w') as f: f.write('dummy data') # Initialize the BIDSLayout layout = BIDSLayout(dummy_bids_dir, validate=False) # Query for files t1w_files = layout.get(subject='01', suffix='T1w', extension='.nii.gz') print(f"Found {len(t1w_files)} T1w files for subject 01:") for f in t1w_files: print(f.path) # Clean up dummy directory (optional) # import shutil # shutil.rmtree(dummy_bids_dir)

Debug

Known issues

breakingPyBIDS versions 0.21.0 and higher require Python 3.10+. Support for Python 3.9 was dropped. Additionally, minimum versions for core scientific dependencies (NumPy, SciPy, NiBabel, Pandas) were raised.

fix

Upgrade your Python environment to 3.10 or newer. Ensure all scientific computing dependencies (NumPy, SciPy, NiBabel, Pandas) meet or exceed the specified minimum versions (e.g., NumPy >=1.24, Pandas >=2.0).

affects: 0.21.0+

breakingAs of PyBIDS 0.20.0, several previously deprecated behaviors now raise errors. Specifically, passing indexer arguments directly to `BIDSLayout` or `BIDSLayout.get()` (e.g., `indexer_args`) and disabling `absolute_paths` mode in `BIDSLayout()` or `BIDSLayout.get()` are no longer allowed.

fix

To control indexing behavior, create an explicit `BIDSLayoutIndexer` instance and pass it to the `BIDSLayout` constructor. Ensure all file paths are handled as absolute paths, as disabling this mode is no longer supported.

affects: 0.20.0+

gotchaPyBIDS 0.19.0 added support for '+' signs in BIDS labels and suffixes, anticipating BIDS specification updates. However, files using these '+' signs will not pass validation if using `bidsschematools` versions prior to the official BIDS specification update.

fix

Be aware that while `pybids` can index these files, BIDS validation tools might flag them as invalid until the BIDS specification and `bidsschematools` are updated to reflect this change.

affects: 0.19.0+

gotchaIn PyBIDS versions 0.9.0 through 0.16.3, boolean metadata fields with a value of `False` were incorrectly read as `True` when using SQL indexing.

fix

Upgrade to PyBIDS 0.16.4 or later to ensure boolean metadata fields are correctly interpreted.

affects: 0.9.0 - 0.16.3

Errors

Common errors & fixes

TypeError: BIDSLayout.get() got an unexpected keyword argument 'absolute_paths'

Attempting to disable `absolute_paths` or pass indexer arguments directly to `BIDSLayout.get()` in PyBIDS 0.20.0 or newer.

fix

This functionality was removed. All paths are now absolute. For indexer configuration, use `BIDSLayoutIndexer` when initializing `BIDSLayout`.

ImportError: cannot import name 'BIDSLayout' from 'pybids.layout'

Using an incorrect import path for `BIDSLayout`.

fix

The main `BIDSLayout` class is available directly under the top-level `bids` package. Use `from bids import BIDSLayout`.

RuntimeError: bids-validator returned non-zero exit code

The BIDS dataset being indexed or validated contains structural errors or does not conform to the BIDS specification, and `validate=True` (default) was used in `BIDSLayout` initialization.

fix

Inspect the output of the validator for specific errors. Rectify issues in your BIDS dataset. Alternatively, initialize `BIDSLayout(..., validate=False)` to skip validation, but be aware this may lead to issues if the data is severely malformed.

KeyError: 'Cannot find field with name 'my_custom_entity''

Attempting to query a BIDSLayout for a custom entity that is not defined in the BIDS specification patterns or custom patterns provided to the layout.

fix

Ensure your custom entity is correctly defined in a custom BIDS pattern file and loaded into the `BIDSLayout` instance upon initialization (e.g., `BIDSLayout(..., config=['my_custom_config.json'])`).

Upgrade

Version history

0.22.0latest on PyPI · released Mar 12, 2026

Audit

Dependencies

pythonrequiredMinimum Python version for recent releases

numpyrequiredCore dependency for numerical operations

scipyrequiredCore dependency for scientific computing

pandasrequiredUsed for data manipulation and tabular output

nibabelrequiredUsed for reading/writing neuroimaging file formats

universal_pathlibrequiredEnables support for cloud and other non-local file systems

bidsschematoolsrequiredRequired for BIDS dataset validation

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bids-standard/pybids ↗

packagehttps://pypi.org/project/pybids/ ↗