Install & Compatibility
Where this runs
tested against v4.3.1 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.290s · 409.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 18.7s · import 1.203s · 398MB
416MB installed
● package 416MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
rdrecord
✓ record = wfdb.rdrecord('record_name')
Reads a WFDB record into a Record object.
rdsamp
✓ signals, fields = wfdb.rdsamp('record_name')
Reads WFDB signals and returns a NumPy array and a dictionary of metadata.
plot_wfdb
✓ wfdb.plot_wfdb(record=record, title='Record X')
Plots WFDB records and annotations. Requires a Record object.
Annotation
✓ annotation = wfdb.rdann('record_name', 'atr')
Reads WFDB annotation files into an Annotation object.
This quickstart example demonstrates how to import the `wfdb` library, download and read a record from the PhysioNet 'mitdb' database, plot the physiological signals, and access key metadata like signal data, sampling frequency, and signal names. The `plt.show()` call is important for displaying plots in many environments.
import wfdb
import matplotlib.pyplot as plt
# Download and read a WFDB record from PhysioNet
# '100' is a record name, 'mitdb' is the PhysioNet database directory
record = wfdb.rdrecord('100', pn_dir='mitdb')
# Plot the signal
wfdb.plot_wfdb(record=record, title='Record 100 from MIT-BIH Arrhythmia Database', figsize=(10, 4))
plt.show() # Crucial for displaying plots in non-interactive environments
# Access signal data and metadata
signals = record.p_signal # Physical signals as NumPy array
fs = record.fs # Sampling frequency
sig_names = record.sig_name # Signal names
print(f"Signals shape: {signals.shape}")
print(f"Sampling frequency: {fs} Hz")
print(f"Signal names: {sig_names}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'wfdb'
The 'wfdb' package is not found in the Python environment currently being used by your interpreter, IDE, or Jupyter Notebook. This often happens with multiple Python installations or when using `pip install --user`.
fixEnsure you are running your code with the Python interpreter where `wfdb` was installed. In Jupyter, check the kernel. If using virtual environments, activate the correct one. Reinstall using `pip install wfdb` in the intended environment.
Plot not showing up (e.g., when calling wfdb.plot_wfdb in a script)
In non-interactive Python scripts or certain IDEs, Matplotlib plots do not automatically display. `wfdb.plot_wfdb` uses Matplotlib internally.
fixAdd `import matplotlib.pyplot as plt` and `plt.show()` after calling `wfdb.plot_wfdb()` or `wfdb.plot_items()` to explicitly render and display the plot.
IOError: Cannot find header file for record: 'record_name' (or similar 'record not found' error)
The specified WFDB record files (.hea, .dat, etc.) could not be found. This could be due to an incorrect local path, or if you're trying to access records from PhysioNet without specifying the correct PhysioNet directory (`pn_dir`).
fixFor local files, ensure `record_name` is the correct path to the record files. For PhysioNet data, specify the `pn_dir` argument (e.g., `wfdb.rdrecord('100', pn_dir='mitdb')`) and ensure you have an active internet connection. Upgrade
Version history
4.3.1latest on PyPI · released Feb 3, 2026
Audit
Dependencies
numpyrequiredCore numerical operations for signal data.
pandasrequiredData structures, especially for `Record.to_dataframe()` functionality.
scipyrequiredScientific computing support, including signal processing tools.
matplotlibrequiredSignal visualization and plotting.
scikit-learnoptionalFor scientific models and analysis, optional for core I/O.
libsndfileoptionalRequired on some less common systems for sound file handling.