YORU (Your Optimal Recognition Utility)

YORU logo YORU demonstration

“YORU” (Your Optimal Recognition Utility) is an open-source animal behavior detection system using Python. YORU can detect animal behaviors, not only single-animal behaviors but also social behaviors. YORU also provides online/offline analysis and closed-loop manipulation.

“YORU: Animal behavior detection with object-based approach for real-time closed-loop feedback”

Versions

Channel	Version	Notes
Latest Release	v1.1.2	Stable release recommended for general use
Latest Beta	v2.0.0-beta.4	Preview of the next major version — may contain bugs

To use the beta version, check out the corresponding tag:
git checkout v2.0.0-beta.4
The v2.0 betas launch without Google Chrome. Beta 4 brings YOLOv5 back, so models trained with YORU v1 load again. It also moves PyTorch to the CUDA 12.8 build for RTX 50-series GPUs, which needs NVIDIA driver 570 or newer, and corrects the Evaluation sub-module’s AP. Read the Beta Release Notes before installing or upgrading.

What’s new in v1.1.2

macOS and Linux: the uv environment now builds on Windows, Linux and macOS 14+ (Apple Silicon) from a single lockfile.
Automatic compute device: YORU picks CUDA, then Apple MPS, then the CPU. Override it with YORU_DEVICE or the device selector in the Training GUI.
More models: the Training GUI trains YOLOv5, YOLOv8, YOLO11, RT-DETR, Faster R-CNN, Mask R-CNN and SSD.
Error logs: errors are shown on screen and written to ~/.yoru/logs/yoru.log.
No CUDA toolkit needed: only the NVIDIA driver. The PyTorch wheels carry their own CUDA runtime.

See the release page for the full list.

Features

Comprehensive Behavior Detection: Recognizes both single-animal and social behaviors, and allows for user-defined animal appearances using deep learning techniques.
Online/Offline Analysis: Supports real-time and post-experiment data analysis.
Closed-Loop Manipulation: Enables interactive experiments with live feedback control.
User-Friendly Interface: Provides a GUI.
Customizable: Allows you to customize various hardware manipulations in closed-loop systems.

Quick install

These steps install the stable release (v1.1.2). The Install guide has the details, including the prerequisites for macOS.

Before you start, install:

Google Chrome or Chromium. The v1.1.x launcher opens in it. Microsoft Edge and Safari do not work.
An NVIDIA GPU driver that supports CUDA 12.x, to use a GPU on Windows or Linux. You do not need the CUDA toolkit.

Install with uv (Windows, Linux, macOS)

Install uv.

Windows (PowerShell):

 winget install --id=astral-sh.uv -e

macOS / Linux:

 curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the repository and build the environment.

 git clone https://github.com/Kamikouchi-lab/YORU.git
 cd YORU
 uv sync

Run YORU from the repository folder.
```
 uv run yoru
```

Install with conda (Windows, Linux)

Download or clone the YORU project.

 cd "Path/to/download"
 git clone https://github.com/Kamikouchi-lab/YORU.git

Create a virtual environment with the YORU.yml file (Python 3.10):
```
  conda env create -f "Path/to/YORU.yml"
```
Activate the virtual environment in the command prompt or Anaconda prompt.
```
  conda activate yoru
```

Install PyTorch. The cu118 / cu121 choice has to be one that your driver supports.

For CUDA==11.8

 pip install torch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 --index-url https://download.pytorch.org/whl/cu118

For CUDA==12.1

 pip install torch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 --index-url https://download.pytorch.org/whl/cu121

Run YORU from the YORU project folder.

 conda activate yoru
 cd "Path/to/YORU/project/folder"
 python -m yoru

Learn about YORU

User guides — for the stable release (v1.1.2)
Beta guides — for v2.0.0-beta.4
YORU Tracker — the tracking sister application: persistent IDs, trajectories and per-animal tracks on top of YORU’s detectors (needs v2.0.0-beta.4 or later)
YORU-Explain — the explanation sister application: which parts of a frame one detection’s score depends on (occlusion sensitivity, Grad-CAM); in development, needs v2.0.0-beta.4 or later
YORU Ecosystem — how YORU, its sister applications and the trigger plugins fit together
Step-by-Step Tutorial
Testing Guide
Q and A

Requirements

OS

Windows 10 or later, with an NVIDIA GPU. This is the primary target, and the only platform tested end to end, including the closed-loop hardware.
Linux, with an NVIDIA GPU. It uses the same CUDA wheels as Windows, but has had much less testing.
macOS 14 (Sonoma) or later on Apple Silicon, installed with uv. Intel Macs are not supported.

Hardware

Memory: 16 GB RAM or more
GPU: an NVIDIA GPU with a driver that supports CUDA 12.x, or an Apple Silicon (M-series) Mac, which uses MPS. YORU also runs on the CPU alone, but detection is much slower.

Software

Python 3.10. uv installs it for you, and the conda environment file pins it.
Google Chrome or Chromium, for the launcher window (v1.1.x only; the v2.0 betas need no browser).
On macOS only: the Xcode Command Line Tools, and the Camera / Input Monitoring / Screen Recording permissions.

Development environments

OS: Windows 11
CPU: Intel Core i9 (11th)
GPU: NVIDIA RTX 3080
Memory: DDR4 32 GB

Reference

Hayato M. Yamanouchi et al., YORU: Animal behavior detection with object-based approach for real-time closed-loop feedback. Sci. Adv. 12, eadw2109 (2026). DOI:10.1126/sciadv.adw2109
Yamanouchi, H. M., Takeuchi, R. F., Chiba, N., Hashimoto, K., Shimizu, T., Tanaka, R., & Kamikouchi, A. (2024). YORU: social behavior detection based on user-defined animal appearance using deep learning. bioRxiv (p. 2024.11.12.623320). https://doi.org/10.1101/2024.11.12.623320

License:

AGPL-3.0 License: YORU is intended for research/academic/personal use only. See the LICENSE file for more details.

Third-Party Libraries and Licenses

This project includes code from the following repositories:

LabelImg: Licensed under the MIT License
yolov5: Licensed under the AGPL-3.0 License

YORU Your Optimal Recognition Utility