openneuro-py

A Python client for accessing OpenNeuro datasets.

openneuro-py in action

Run without installation (uvx)

You can run openneuro-py directly without installing it using uvx:

# Download a dataset without installing the package
uvx openneuro-py@latest download --dataset=ds000246

# Get help
uvx openneuro-py@latest --help

Installation into a Python project

Choose one of the following methods:

# via uv (recommended):
uv add openneuro-py

# via conda:
conda install -c conda-forge openneuro-py

# via pip:
pip install openneuro-py

Optional: Jupyter and IPython support

For enhanced support in Jupyter Lab, Jupyter Notebook, IPython interactive sessions, and VS Code's interactive Jupyter interface, install ipywidgets:

# via uv:
uv add ipywidgets

# via conda:
conda install -c conda-forge ipywidgets

# via pip:
pip install ipywidgets

Basic usage – command line interface

Note: If you're using uvx instead of installing the package, prefix all commands below with uvx and invoke openneuro-py@latest to use the latest released version. For example, openneuro-py --help becomes uvx openneuro-py@latest --help.

Getting help

openneuro-py --help
openneuro-py download --help
openneuro-py login --help

Download an entire dataset

openneuro-py download --dataset=ds000246

Specify a target directory

To store the downloaded files in a specific directory, use the --target-dir switch. The directory will be created if it doesn't exist already.

openneuro-py download --dataset=ds000246 \
                      --target-dir=data/bids

Continue an interrupted download

Interrupted downloads will resume where they left off when you run the command again.

Advanced usage – command line interface

Exclude a directory from the download

openneuro-py download --dataset=ds000246 \
                      --exclude=sub-emptyroom

Download only a single file

openneuro-py download --dataset=ds000246 \
                      --include=sub-0001/meg/sub-0001_coordsystem.json

Note that a few essential BIDS files are always downloaded in addition.

Download or exclude multiple files

--include and --exclude can be passed multiple times:

openneuro-py download --dataset=ds000246 \
                      --include=sub-0001/meg/sub-0001_coordsystem.json \
                      --include=sub-0001/meg/sub-0001_acq-LPA_photo.jpg

Use an API token to log in

To download private datasets, you will need an API key that grants you access permissions. Go to OpenNeuro.org, My Account → Obtain an API Key. Copy the key, and run:

openneuro-py login

Paste the API key and press return.

Basic usage – Python interface

import openneuro as on
on.download(dataset='ds000246', target_dir='data/bids')

Development

This project uses uv for dependency management and building.

Pre-commit hooks are run through lefthook.

Setup development environment

# Clone the repository
git clone https://github.com/hoechenberger/openneuro-py.git
cd openneuro-py

# Install dependencies and create virtual environment
uv sync --locked

# Optional: Install pre-commit hooks
uv run lefthook install

# Run tests
uv run pytest

# Run the CLI during development
uv run openneuro-py --help

Building

# Build the package
uv build

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openneuro_py-2026.7.1.tar.gz (331.0 kB view details)

Uploaded Jul 27, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

openneuro_py-2026.7.1-py3-none-any.whl (33.7 kB view details)

Uploaded Jul 27, 2026 Python 3

File details

Details for the file openneuro_py-2026.7.1.tar.gz.

File metadata

Download URL: openneuro_py-2026.7.1.tar.gz
Upload date: Jul 27, 2026
Size: 331.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for openneuro_py-2026.7.1.tar.gz
Algorithm	Hash digest
SHA256	`ee885a46859235ae62d27ce612ee49b6a330fd0eac276e7f58b6018d8af859d1`
MD5	`8756cf07e1dd3a0a52248005de5b33ca`
BLAKE2b-256	`a206f7ba75a616cf3936900fda8bec252918111350b9f030719afb2aefbb45fa`

See more details on using hashes here.

File details

Details for the file openneuro_py-2026.7.1-py3-none-any.whl.

File metadata

Download URL: openneuro_py-2026.7.1-py3-none-any.whl
Upload date: Jul 27, 2026
Size: 33.7 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for openneuro_py-2026.7.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`295a69c6532fd5475954c40b4071e5911585aa4dabc30bf34afc17ece3340e6e`
MD5	`32d405e717b462dadb08eda374bb69e2`
BLAKE2b-256	`f75c6f70eae8182a1e466d342b34510d2aea27ed725aeceab70917b770005acc`