Skip to main content

A lightweight I/O utility for the BrainVision data format.

Project description

CircleCI codecov pypi Downloads Documentation Status


pybv is a lightweight exporter to the BrainVision data format. It is meant for use with electrophysiology datasets stored in the Brain Imaging Data Structure.

The documentation can be found under the following links:

About the BrainVision data format

BrainVision is the name of a file format commonly used for storing electrophysiology data. Originally, it was put forward by the company Brain Products, however the simplicity of the format has allowed for a diversity of tools reading from and writing to the format.

The format consists of three separate files:

  1. A text header file (.vhdr) containing meta data
  2. A text marker file (.vmrk) containing information about events in the data
  3. A binary data file (.eeg) containing the voltage values of the EEG

Both text files are based on the Microsoft Windows INI format consisting of:

  • sections marked as [square brackets]
  • comments marked as ; comment
  • key-value pairs marked as key=value

A documentation for core BrainVision file format is provided by Brain Products. You can view the specification as hosted by Brain Products.


pybv’s only dependency is numpy. However, we currently recommend that you install MNE-Python for reading BrainVision data. See their instructions here.

After you have a working installation of MNE-Python (or only numpy if you don’t want to read data and only write it), you can install pybv through the following: pip install -U pybv


The development of pybv is taking place on Github.

For more information, please see


Writing BrainVision files

The primary functionality provided by pybv is the write_brainvision function. This writes a numpy array of data and provided metadata into a collection of BrainVision files on disk.

from pybv import write_brainvision

# for further parameters see our API documentation in the docs
write_brainvision(data, sfreq, ch_names, fname, tmpdir, events,
                  resolution=1e-6, fmt='binary_float32')

Reading BrainVision files

Currently, pybv recommends using MNE-Python for reading BrainVision files written with pybv. This results in a nearly-round-trip conversion of the data (up to the numerical precision you specify in the resolution parameter).

Here is an example of the MNE code required to read in BrainVision data:

import mne

# Import the BrainVision data into an MNE Raw object
raw ='tmp/test.vhdr', preload=True)

# Read in the event information as MNE annotations
annot = mne.read_annotations('tmp/test.vmrk')

# Add the annotations to our raw object so we can use them with the data

# Reconstruct the original events from our Raw object
events, event_ids = mne.events_from_annotations(raw)


This package was originally adapted from the Philistine package by palday. It copies much of the BrainVision exporting code, removes the dependence on MNE, and focuses the code around BrainVision I/O.

Project details

Download files

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

Files for pybv, version 0.2.0
Filename, size File type Python version Upload date Hashes
Filename, size pybv-0.2.0-py3-none-any.whl (9.0 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pybv-0.2.0.tar.gz (8.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page