bids-utils
A CLI and Python library for manipulating BIDS datasets: rename files,
subjects, sessions, and runs; migrate datasets between BIDS versions;
aggregate, segregate, and audit metadata; merge and split datasets.
Schema-driven throughout (via bidsschematools) and aware of
version control, including git-annex and DataLad datasets.
⚠️ Status: early development. APIs, CLI commands, and behaviors may change before the first tagged release.
What it does
- File / subject / session / run renaming with sidecar,
_scans.tsv, andparticipants.tsvupdates, plus BIDS URI fix-up. - Schema-driven migration between BIDS versions, including 1.x
deprecation fixes and 2.0 structural changes. Tiered rule levels
(
safe/advisory/non-auto-fixable). - Metadata management — aggregate, segregate, and audit inheritance chains across sidecar JSONs.
- Dataset-level operations —
merge,split,remove. - VCS-aware — git, git-annex, and DataLad backends; annexed content
is fetched / unlocked / re-added as needed (
--annexed=get).
Install
# one-shot (isolated) invocation
uvx bids-utils --help
# inside a project env
uv pip install bids-utils # or: pip install bids-utils
Commands
$ bids-utils --help
Usage: bids-utils [OPTIONS] COMMAND [ARGS]...
CLI for manipulating BIDS datasets.
Options:
--version Show the version and exit.
--annexed [error|get|skip-warning|skip]
How to handle git-annex files without local
content.
-h, --help Show this message and exit.
Commands:
completion Output shell completion activation script.
merge Merge multiple BIDS datasets.
metadata Metadata manipulation commands.
migrate Apply schema-driven migrations to resolve deprecations.
remove Remove a subject from the dataset.
remove-run Remove a run and optionally reindex subsequent runs.
rename Rename a BIDS file and all its sidecars.
session-rename Rename a session.
split Extract a subset of a BIDS dataset.
subject-rename Rename a subject across the entire dataset.
Run bids-utils <COMMAND> --help for per-command options.
Quick tour
# Rename a BOLD file; sidecars and _scans.tsv follow automatically.
bids-utils rename path/to/sub-01_task-rest_bold.nii.gz --set task=nback
# Migrate an older 1.x dataset to the current 1.x release.
bids-utils migrate /data/ds001 --dry-run
# Rename a subject across the whole dataset (VCS-aware).
bids-utils subject-rename /data/ds001 --from 01 --to 99
The same operations are available as a Python library:
from bids_utils import BIDSDataset
from bids_utils.subject import rename_subject
ds = BIDSDataset.from_path("/data/ds001")
rename_subject(ds, old="01", new="99")
Shell completion
bids-utils completion emits an activation script for the detected
shell (bash, zsh, or fish) with BIDS-aware suggestions for sub-*,
ses-*, and entity keys from the schema.
# Enable for the current shell (one-shot):
eval "$(bids-utils completion)"
# Persist it: append to your shell rc file.
echo 'eval "$(bids-utils completion)"' >> ~/.bashrc # or ~/.zshrc
For fish:
bids-utils completion fish | source
Contributing
See CONTRIBUTING.md for tooling conventions, the
pre-commit tox gate, and where to find the design documents under
.specify/specs/. Integration tests use the bids-examples
submodule — run git submodule update --init --recursive after
cloning.
License
Apache License 2.0.
Metadata
Release files for bids-utils 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bids_utils-0.1.2.tar.gz | 16.6 MB | Without provenance | Details for bids_utils-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bids_utils-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for bids_utils-0.1.2-py3-none-any.whl |
Total release size: 16.7 MB
Release files / bids_utils-0.1.2.tar.gz
| Download URL | bids_utils-0.1.2.tar.gz |
|---|---|
| Size | 16.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
08887e13bff10e333cb93bfcf64efa43189ae70eb11711dbd1c342f7f4fef1c0
|
|
BLAKE2b-256 checksum How to use checksums |
4709e086105c9a212b5cf8e609bfc3149f059ffadaef921bdf02c066f30cdfb5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / bids_utils-0.1.2-py3-none-any.whl
| Download URL | bids_utils-0.1.2-py3-none-any.whl |
|---|---|
| Size | 59.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5b7084e01b7bff1b5e1a77ea032aa9e8b3576aff338c6e13aae0b25fbf98098a
|
|
BLAKE2b-256 checksum How to use checksums |
b70b039fcac533280e64eab28ae06e97298b84917c71b55151f611d9d13c891f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for bids-utils 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.