bearing-datasets

69 public bearing and rotating-machinery fault datasets in one common format, downloaded from their original sources. Every dataset becomes one metadata table (one row per signal) plus the signals themselves, ready for pandas, polars, NumPy or PyTorch.

Why:

• Reproducible: data comes from the official sources (with mirrors as fallback) and is checked against pinned checksums; the build records what was used.
• Same format for every dataset: the same column names and labels, so code written for one dataset works on the others.
• Build once: each dataset is built once into a folder you choose (on your laptop or on a server), then read from there. A team can point everyone to the same folder.
• Fast and light: compressed Parquet files; read one signal without loading the rest.

Important: code only, no data. Each dataset is downloaded by you from its original source and keeps its own license, set by its authors. Confirm the license of every dataset before you use it: see License.

New here? Read the guide (concepts, recipes, FAQ) and run the notebook examples/usage.ipynb. Have a dataset that is not listed? Add it. Using it in a paper? Please cite it.

Contents

• Quick start: install, choose a folder, build, read
• Datasets: the list of datasets, what they contain and their size
• Concepts in one minute: recordings, channels, signals, metadata
• API: Python functions and command line
• The metadata table: the columns and their values
• On disk: the files of a built dataset
• Documentation: guide, notebook, contributing
• Add your dataset · Development with AI · Citing · License

Quick start

1. Install the package from PyPI (no need to clone the repository):

pip install bearing-datasets
# or, in a uv project:
uv add bearing-datasets

Add the polars extra (pip install "bearing-datasets[polars]") to get the metadata as a polars DataFrame. The latest development version installs from GitHub: pip install "bearing-datasets @ git+https://github.com/VictorBauler/BearingDatasets".

Command not found? (common on Windows, e.g. "bearing-datasets is not recognized") uv add installs the command inside the project's .venv, which is not on your PATH. Run it through uv from the project folder, uv run bearing-datasets list, or activate the environment first (.venv\Scripts\activate on Windows, source .venv/bin/activate elsewhere). To have the command everywhere, install it as a tool instead: uv tool install bearing-datasets then uv tool update-shell and open a new terminal. The examples below write bearing-datasets ...; prefix them with uv run if needed.

Clone the repository only to change the code or add a dataset (see CONTRIBUTING.md); there, uv sync installs everything, including the notebook and test tools.

2. Choose the datasets folder (any folder; a team can share one on a server). This is saved for your user, so you only do it once, on Linux, macOS or Windows:

bearing-datasets root /data/bearing_datasets     # Windows: bearing-datasets root D:\datasets
bearing-datasets root                               # shows the current folder

The same from Python: bd.set_root("/data/bearing_datasets"). A different folder can still be used for one command (--root) or one call (root=...), and the environment variable BEARING_DATASETS_ROOT, when set, takes priority over the saved folder.

3. Download the datasets you need. Check which ones are already there: datasets marked [built] are ready to use.

bearing-datasets list

Nothing is downloaded until you ask for it. Build (download + convert) only the datasets that are missing; this is done once per folder (and anyone sharing the folder can use them):

bearing-datasets build cwru                 # one dataset
bearing-datasets build cwru hust paderborn  # several; resumable, downloads cached in <root>/_raw/

For large datasets you can store only a part (the download is the same, the disk used is smaller). A subset gets its own name, so it never replaces the full dataset:

bearing-datasets build bjtu_bogie --channels CH1 CH2 CH3 --where load=0 --as bjtu_motor_de

4. Use them in Python:

import bearing_datasets as bd

ds = bd.open("cwru")                         # fails with a hint if cwru is not built yet
meta = ds.metadata()                         # pandas DataFrame, one row per signal
inner = meta[(meta.condition == "inner") & (meta.fs == 12000)]

x = ds.signal(inner.signal_id.iloc[0])     # one signal, as a numpy array
df = ds.with_signals(inner)                  # the same rows + a "signal" column

Datasets

69 datasets in 4 groups: bearing test rigs (37), machines with several fault types (22), run-to-failure (9), field data (1). How many distinct physical bearings each one has (for leave-bearing-out evaluation): docs/diversity.md.

Bearing test rigs (37)

Seeded or natural bearing faults on laboratory rigs.

Machines with several fault types (22)

Motors, gearboxes, pumps and bogies; bearing faults among others.

Run-to-failure (9)

Bearings recorded periodically until they fail.

Field data (1)

Real machines in operation.

download is what is fetched from the sources; on disk is the built dataset. Downloads are kept in <root>/_raw/ so datasets can be rebuilt without downloading again, so the space needed is roughly download + on disk (you can delete _raw/ if space is short, at the cost of downloading again to rebuild). To store less, build only part of a dataset (see subsets).

bearing-datasets info <name> shows the details, license and citation of each dataset (see License).

Your own datasets (e.g. private lab data) are built from files on your disk, without changing the package. Write a dataset.yaml whose source points to the folder of raw files, and a builder.py that reads them:

sources:
  - {type: local, path: ~/data/my_rig, include: ["*.mat"]}

bearing-datasets build ~/my_datasets/my_rig   # first time, by the path of the definition
bearing-datasets info my_rig                   # afterwards, by name; bd.open("my_rig")

The full walkthrough is in Private datasets, and a working example is examples/private_datasets/my_cwru (four CWRU files read from a local folder).

Concepts in one minute

• A dataset is one published dataset, e.g. cwru: ds = bd.open("cwru").
• A recording is one acquisition: the machine ran in one condition (fault, speed, load) and one or more channels were recorded at the same time. Id: recording_id, e.g. 12k_DE_IR007_1.
• A channel is one sensor, or one axis of a sensor, e.g. DE (the drive-end accelerometer).
• A signal is one channel of one recording. Id: signal_id = <recording_id>/<channel>, e.g. 12k_DE_IR007_1/DE. Its samples are a numpy array: ds.signal(signal_id); all the channels of a recording at once: ds.recording(recording_id).
• The metadata is a table with one row per signal, saying what it is: condition, sensor location, sampling rate, speed, load, ...

API

Command line (prefix with uv run if the command is not found):

The metadata table

One row per signal. These columns exist in every dataset:

Columns that only some datasets have:

Dataset-specific columns (the unsw run-to-failure data counts shaft cycles instead of seconds):

ds.columns() (or bearing-datasets info <name>) gives the exact meaning of every column in a dataset, including dataset notes such as how bearing_id was defined.

Three rules to keep in mind:

• No missing values. When a value does not apply the table says none (e.g. fault_origin of a healthy bearing); when the dataset does not document it, unknown.
• condition describes the machine, not the sensor. A CWRU fan-end signal recorded with a faulty drive-end bearing has condition="inner", fault_location="bearing_de" and sensor_location="bearing_fe". Compare sensor_location with fault_location to know whether the sensor sits on the faulty bearing.
• No train/test splits are included. They belong to each study; use bearing_id (or recording_id) to split without leakage.

Bearing fault frequencies (BPFO, BPFI, …) are in each dataset's description.

On disk

<root>/
  _raw/                           downloaded files, shared by all datasets and users
  <dataset>/
    metadata.parquet              one row per signal
    signals/part-<dtype>.parquet  signal_id + signal, zstd compressed
    manifest.json                 sources used, raw file checksums, content hash, citation,
                                  column descriptions

The metadata can be read without this library: pd.read_parquet(f"{root}/cwru/metadata.parquet").

Documentation

• docs/guide.md: concepts, recipes (windows, splits, resampling, several datasets, PyTorch), notes on each dataset, FAQ
• examples/usage.ipynb: a runnable guided tour (download it and open it in any Jupyter environment where the package is installed)
• CONTRIBUTING.md: add a public dataset to the package, or build a private one (internal lab data) without changing this repository

Add your dataset

Contributions are welcome! If you published a bearing or rotating-machinery dataset, or know a public one that is missing, please add it: it makes the data easier to find, to compare and to cite. A dataset is a folder with a short dataset.yaml (sources, license, citation) and a builder.py that reads the raw files. CONTRIBUTING.md explains the steps. You can also open an issue with a link to the data and we will look into adding it.

Development with AI

This library was developed with the help of AI coding assistants (Claude Code). The code, dataset definitions and documentation were reviewed, and the builds were checked against the original records, but errors can still occur. If you find one (a wrong label, count, sampling rate, license or description, or a bug), please open an issue.

Citing

If this library helps your work, please cite it, together with each dataset you use (ds.cite() or bearing-datasets info <name>; see License). Citing the repository lets others find the same data and reproduce your results.

@software{bauler_bearing_datasets,
  author  = {Bauler, Victor},
  title   = {bearing-datasets: public bearing fault datasets in one common format},
  year    = {2026},
  doi     = {10.5281/zenodo.23062167},
  url     = {https://github.com/VictorBauler/BearingDatasets}
}

This DOI always points to the latest version; each release also has its own DOI, listed on Zenodo, to cite the exact version you used.

License

The code of this repository is released under the MIT license (see LICENSE), provided "as is", without warranty, including for the correctness of the downloaded data and of its labels. The MIT license covers the code only, not the datasets.

This repository does not contain or redistribute any dataset. It holds code and metadata (download addresses, checksums, descriptions). The data is downloaded by you, from the source published by each dataset's authors (or a public mirror of it), when you run build.

• Every dataset keeps its own license and terms. This package grants no rights on the data. You are responsible for confirming the license of each dataset you use, on its original page (bearing-datasets info <name> shows the source and a summary of the license), and for respecting it.
• Licenses differ a lot between datasets. Some allow any use with attribution (e.g. CC BY), some forbid commercial use (e.g. CC BY-NC, including inside a company's products or services), and some state no license at all. Without a license, the authors keep all rights: ask them before any commercial use or redistribution.
• Cite the authors of every dataset you use. Most licenses (CC BY) require it. The citation given by ds.cite() and bearing-datasets info is a suggestion: besides the dataset itself, it may include a paper that is not the dataset's own reference (e.g. the Smith & Randall benchmark study for CWRU). Check the original source for the citation its authors ask for.
• Do not redistribute built datasets (the Parquet files) or the download cache (_raw/) unless the dataset's license allows it. Sharing a built folder inside your own team is fine as long as every user respects the licenses.
• The license, description and labels of each dataset in this repository are summaries made in good faith. They may be incomplete or out of date. The original source and its authors are authoritative.
• This project is not affiliated with or endorsed by the dataset authors or their institutions. Their names are used only to identify the datasets.

Dataset authors: if you want your dataset removed from this library, or described differently, open an issue and we will do it. If you want it added, see Add your dataset.