<a id="setup"></a>

# Setup

This document describes how to install CapyMOA and its dependencies. CapyMOA is
tested against Python 3.11, 3.12, and 3.13. Newer versions of Python will likely
work but have yet to be tested.

Once you have installed the [Dependencies](#dependencies), you may
install CapyMOA using pip (optionally in a [Virtual Environment](#venv)):

```bash
pip install capymoa
```

To verify your installation, run:

```bash
python -c "import capymoa; print(capymoa.__version__)"
```

<a id="venv"></a>

## Virtual Environment

We recommend using a virtual environment to isolate CapyMOA and its dependencies
from your other projects. This is especially important if you have other
projects that require different versions of the same dependencies.

If you chose to use a virtual environment, you have some choices:

* **uv**
  [uv](https://docs.astral.sh/uv/) is a fast Python package and project
  manager. You can create a new virtual environment with:
  ```bash
  uv venv .capymoa-venv
  source .capymoa-venv/bin/activate
  # On Windows, use `.capymoa-venv\Scripts\activate`
  ```
* **Python Virtual Environment**
  PyVenv is a built-in tool for creating virtual
  environments in Python. You can create a new virtual environment with:
  ```bash
  python3 -m venv .capymoa-venv
  source .capymoa-venv/bin/activate
  # On Windows, use `.capymoa-venv\Scripts\activate`
  ```
* **Conda Environment**
  Miniconda is a good choice for managing Python environments. You can install
  Miniconda from [here](https://docs.conda.io/en/latest/miniconda.html).
  Once you have Miniconda installed, you can create a new environment with:
  ```bash
  conda create -n capymoa python=3.11
  conda activate capymoa
  ```

  When your environment is activated, you can install CapyMOA by following the
  instructions below.

<a id="dependencies"></a>

## Dependencies

CapyMOA has some required dependencies that may require manual installation
before CapyMOA can be used:

### Java

CapyMOA requires Java 9 or later (Java 8 and earlier are not supported by
CapyMOA’s underlying JPype library). We recommend a current LTS release such
as Java 17 or 21. You can check your Java version by running the following
command in your terminal:

```bash
java -version
```

If Java is not installed, you can download OpenJDK (Open Java Development
Kit) from [this link](https://openjdk.org/install/), or alternatively the
Oracle JDK from [this link](https://www.oracle.com/java).  You only need
to install the Java Runtime (JRE). Linux and macOS users can also install
OpenJDK using their distribution’s package manager:

### Ubuntu

```bash
sudo apt-get install -y default-jre-headless
```

### macOS

```bash
brew install openjdk
```

CapyMOA will attempt to find the Java automatically unless the `JAVA_HOME`
environment variable is set. This allows you to have multiple Java versions
or have Java installed outside of the system path.

### PyTorch

PyTorch is **optional**. `pip install capymoa` does not install it, so the
core of CapyMOA – streams, classifiers, regressors, drift detectors and
evaluation – installs without pulling a deep-learning stack.

The parts of CapyMOA that use deep learning do require it:
[`capymoa.ocl`](../api/modules/capymoa.ocl.md#module-capymoa.ocl), [`capymoa.stream.TorchStream`](../api/modules/capymoa.stream.TorchStream.md#capymoa.stream.TorchStream),
the `Batch*` learners, [`capymoa.anomaly.Autoencoder`](../api/modules/capymoa.anomaly.Autoencoder.md#capymoa.anomaly.Autoencoder),
[`capymoa.classifier.Finetune`](../api/modules/capymoa.classifier.Finetune.md#capymoa.classifier.Finetune) and [`capymoa.ssl.OSNN`](../api/modules/capymoa.ssl.OSNN.md#capymoa.ssl.OSNN). Using one of
those without PyTorch raises an `OptionalDependencyError` telling you what to
install.

[`capymoa.drift.detectors.ABCD`](../api/modules/capymoa.drift.detectors.ABCD.md#capymoa.drift.detectors.ABCD) is a partial case: it works without
PyTorch on its default `model_id="pca"` and on `"kpca"`, and needs the extra
only for the autoencoder model, `model_id="ae"`.

Install CapyMOA with PyTorch using the `torch` extra:

```bash
pip install capymoa[torch]
```

#### NOTE
On Linux the default PyPI PyTorch wheel is CUDA-enabled and pulls the NVIDIA
stack (several GB). If you do not need a GPU, install the CPU build *first*
and then CapyMOA – pip (or uv) will keep the version you already have:

### pip

```bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install capymoa[torch]
```

### uv

```bash
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
uv pip install capymoa[torch]
```

To match a specific GPU or CUDA version instead, follow the instructions
[here](https://pytorch.org/get-started/locally/), and make sure PyTorch goes
into the same virtual environment as CapyMOA.