Installation

The following instructions assume that you have either conda or uv installed. If you don’t please check their installation instructions (for conda, for uv).

Create and activate a virtual environment

To avoid dependency conflicts with other packages, it is best practice to install Python packages within a virtual environment. We recommend using conda or uv to create and manage this environment, as they simplify the installation process.

conda

Create and activate a new conda environment:

# Create conda environment
conda create -y -n ethology-env -c conda-forge python=3.13

# Activate it
conda activate ethology-env

We used ethology-env as the environment name, but you can choose any name you prefer.

uv

Create and activate a new virtual environment inside your project directory:

# Create virtual environment
uv venv --python=3.13

# On macOS and Linux, activate it with:
source .venv/bin/activate

# On Windows PowerShell, activate it with:
.venv\Scripts\activate

Install the package

With your environment activated, install ethology using one of the methods below.

From PyPI using pip

Install the core package:

pip install ethology

From PyPI using uv

Install the core package:

uv pip install ethology

For developers

If you would like to contribute to ethology, see our contributing guide for detailed developer setup instructions and coding guidelines.

Update the package

Always update using the same package manager used for installation (either via pip or via uv).

To update to the latest version of ethology:

pip

pip install -U ethology

uv

uv pip install -U ethology

If the above fails, try installing ethology in a fresh new environment. To do this, first remove the existing environment:

conda

conda env remove -n ethology-env

uv

Delete the .venv folder in your project directory.

# On macOS and Linux, run:
rm -rf .venv

# On Windows PowerShell, run:
rmdir /s /q .venv

Optionally, you can clean the uv cache for unused packages:

uv cache prune

Then you can create a new environment following the instructions above.

Tip

You can list all conda environments before and after the above command to verify removal:

conda env list