{"id":7594,"library":"pynwb","title":"PyNWB","description":"PyNWB is the official Python API for working with Neurodata Without Borders (NWB) files, a standardized data format for neurophysiology data. It facilitates reading, writing, and manipulating NWB files, providing a high-level interface to the underlying HDF5 structure. The current version is 3.1.3, and it maintains an active release cadence with regular minor updates and less frequent major versions supporting new NWB schema versions.","status":"active","version":"3.1.3","language":"en","source_language":"en","source_url":"https://github.com/NeurodataWithoutBorders/pynwb","tags":["neuroscience","nwb","data-format","hdf5","data-acquisition","electrophysiology","optical-physiology"],"install":[{"cmd":"pip install pynwb","lang":"bash","label":"Install PyNWB"}],"dependencies":[{"reason":"Core dependency for HDF5 file operations.","package":"h5py","optional":false},{"reason":"Fundamental for numerical data handling.","package":"numpy","optional":false}],"imports":[{"symbol":"NWBFile","correct":"from pynwb import NWBFile"},{"note":"NWBHDF5IO is directly available from the top-level pynwb package since version 2.0.0. Importing from pynwb.io is deprecated.","wrong":"from pynwb.io import NWBHDF5IO","symbol":"NWBHDF5IO","correct":"from pynwb import NWBHDF5IO"},{"symbol":"TimeSeries","correct":"from pynwb.base import TimeSeries"},{"symbol":"ElectricalSeries","correct":"from pynwb.ecephys import ElectricalSeries"},{"symbol":"ImageSeries","correct":"from pynwb.ophys import ImageSeries"}],"quickstart":{"code":"from datetime import datetime\nfrom pynwb import NWBFile, TimeSeries, NWBHDF5IO\nimport numpy as np\nimport os\n\n# 1. Create a new NWBFile\nnwbfile = NWBFile(\n    session_description='My first NWB file tutorial',\n    identifier='NWB_Tutorial_1',\n    session_start_time=datetime.now().astimezone(),\n    experimenter='John Doe',\n    lab='Neuroscience Lab',\n    institution='University of Example',\n    experiment_description='Simple data creation for testing PyNWB.'\n)\n\n# 2. Add some TimeSeries data\ndata = np.random.rand(100, 1)\ntimestamps = np.linspace(0, 9.9, 100)\nseries = TimeSeries(\n    name='my_timeseries',\n    data=data,\n    timestamps=timestamps,\n    unit='volts',\n    description='A simple random time series.'\n)\n\nnwbfile.add_acquisition(series)\n\n# 3. Write the NWBFile to disk\nfilename = 'quickstart_example.nwb'\nwith NWBHDF5IO(filename, 'w') as io:\n    io.write(nwbfile)\n\nprint(f\"NWB file '{filename}' created successfully.\")\n\n# 4. Read the NWBFile from disk\nwith NWBHDF5IO(filename, 'r') as io:\n    read_nwbfile = io.read()\n    print(f\"\\nRead NWB file. Session description: {read_nwbfile.session_description}\")\n    read_series = read_nwbfile.acquisition['my_timeseries']\n    print(f\"Read TimeSeries data shape: {read_series.data.shape}\")\n    print(f\"Read TimeSeries unit: {read_series.unit}\")\n\n# Clean up the created file\n# os.remove(filename)","lang":"python","description":"This quickstart demonstrates how to create a basic NWB file, add a TimeSeries to it, and then write and read the file from disk using `NWBFile` and `NWBHDF5IO`. It covers the fundamental steps for data archival in the NWB format."},"warnings":[{"fix":"If you rely on the pre-3.0.0 behavior of `pynwb.validate(io=...)` without cached namespaces, update your call to `pynwb.validate(io=..., use_cached_namespaces=False)` to explicitly disable caching for that operation.","message":"The behavior of `pynwb.validate(io=...)` changed in version 3.0.0. It now matches `pynwb.validate(path=...)` and uses cached namespaces. Previous versions did not use cached namespaces for `io` validation.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"These were internal functions. If your code was inadvertently using them, you will need to refactor to use documented public APIs or directly interact with the NWB schema as needed.","message":"Several unused internal functions (e.g., `prepend_string`, `_not_parent` in `core.py`, `_not_parent` in `file.py`, `NWBBaseTypeMapper.get_nwb_file` in `io/core.py`) were removed.","severity":"breaking","affected_versions":">=3.1.0"},{"fix":"Always ensure your NWB file paths end with the `.nwb` extension (e.g., `myfile.nwb`) to adhere to NWB best practices and avoid warnings.","message":"Files written with `NWBHDF5IO` without a `.nwb` extension will trigger a warning.","severity":"gotcha","affected_versions":">=2.8.3"},{"fix":"Upgrade to pynwb version 3.1.2 or later to benefit from the performance fix for large NWB files.","message":"A performance regression introduced in pynwb 2.8.0 affected reading NWB files with a large number of objects or fields of objects.","severity":"gotcha","affected_versions":"2.8.0 - 3.1.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Import `NWBHDF5IO` directly from the top-level `pynwb` package: `from pynwb import NWBHDF5IO`.","cause":"Attempting to import `NWBHDF5IO` from a submodule `pynwb.io` which is not the primary import path for recent pynwb versions.","error":"ModuleNotFoundError: No module named 'pynwb.io'"},{"fix":"Ensure `session_start_time` (a `datetime` object) and `identifier` (a unique string) are always provided during `NWBFile` initialization. Example: `NWBFile(session_description='...', identifier='my_session', session_start_time=datetime.now().astimezone())`.","cause":"When creating an `NWBFile` instance, the `session_start_time` and `identifier` arguments are mandatory according to the NWB schema.","error":"ValueError: NWBFile requires 'session_start_time' and 'identifier'"},{"fix":"Verify the exact name of the object you are trying to access. Use `nwbfile.acquisition.keys()` to list available acquisition objects, or consult the NWB file's structure or the code that generated it.","cause":"This usually means you are trying to access a group or data field within the NWB file (e.g., `nwbfile.acquisition['my_data']`) that does not exist or has a different name.","error":"RuntimeError: Unable to open object (object 'acquisition' not found)"}]}