Installation

Installation

vidlabel is two Python packages. They are installed from a source checkout for now; nothing is published to PyPI yet.

package	what it is	needs
vidlabel-spec	the format: strict models for metadata, views, vocabulary, releases, the frame index	pydantic
vidlabel	the library and the vidlabel command	the spec package, NumPy, PyArrow, zstandard, Typer

Python 3.10 or newer. The test suite is run in CI on Python 3.10 to 3.13 on Linux, and on Python 3.12 on Windows and macOS (see compatibility).

Choose what you need

git clone <your repository URL> && cd vidlabel
pip install -e packages/vidlabel-spec -e packages/vidlabel         # format + library + command line
pip install -e "packages/vidlabel[video]"                          # + OpenCV: read frames, previews, check-video, frame cache
pip install -e "packages/vidlabel[torch]"                          # + OpenCV and PyTorch: the training loaders

you want to	install
read, write, validate and build datasets; use the command line	the first line only
read the format from another program (a different language, a service)	vidlabel-spec alone gives you the models and JSON Schema (vidlabel schema)
draw annotations on real frames, check a file against its metadata, use the frame cache	[video]
feed PyTorch (VideoStream, VideoFrames, PlannedStream)	[torch]

[torch] installs whatever PyTorch pip picks by default. For a GPU build, install PyTorch first by following pytorch.org, then install vidlabel.

ffmpeg (ffprobe)

vidlabel add-video, vidlabel index and probe_video call ffprobe to read the facts about a video file (frame rate as an exact fraction, frame count, size, rotation, codec, and per-frame timestamps). It ships with ffmpeg.

system	command
macOS	brew install ffmpeg
Debian, Ubuntu	sudo apt install ffmpeg
Windows	download a build from ffmpeg.org and add its bin folder to PATH, or choco install ffmpeg

Without ffprobe everything still works except reading facts from a file: you can describe a video by hand with VideoMetadata (see getting started). A missing ffprobe is reported as one clear error, not a traceback.

Check the install

vidlabel --help
vidlabel init demo && vidlabel info demo && vidlabel validate demo

For a development install with the test suite, see development.

Uninstall and upgrade

Datasets are plain folders and are not touched by installing or removing the packages. To upgrade, update the checkout and re-run the pip install -e lines. A newer library opens older datasets of the same spec major version; see compatibility for what changes between versions.

---

Source: docs/installation.md