batdetect2/docs/source/getting_started.md

Getting started

BatDetect2 is both a command line tool (CLI) and a Python library.

• Use the CLI if you want to run existing models or train your own models from the terminal.
• Use the Python package if you want to integrate BatDetect2 into your own scripts, notebooks, or analysis pipeline.

If you want to try BatDetect2 before installing anything locally:

• Hugging Face demo (UK species)
• Google Colab notebook

Prerequisites

We recommend uv for both workflows. uv is a fast Python package and environment manager that keeps installs isolated and reproducible.

• Use uv tool to install the CLI.
• Use uv add to add batdetect2 as a dependency in a Python project.

Install uv first by following their installation instructions.

Install the CLI

The following installs batdetect2 in an isolated tool environment and exposes the batdetect2 command on your machine.

uv tool install batdetect2

If you need to upgrade later:

uv tool upgrade batdetect2

Verify the CLI is available:

batdetect2 --help

Run your first workflow:

Go to {doc}tutorials/run-inference-on-folder for a complete first run.

Integrate with your Python project

If you are using BatDetect2 from Python code, add it to your project dependencies:

uv add batdetect2

This keeps dependency metadata and the environment in sync.

Alternative with pip

If you prefer pip, create and activate a virtual environment first:

python -m venv .venv
source .venv/bin/activate

Then install from PyPI:

pip install batdetect2

What's next

• Run your first detection workflow: {doc}tutorials/run-inference-on-folder
• For practical task recipes, go to {doc}how_to/index
• For command and option details, go to {doc}reference/cli/index