Developer Setup#

If you want to make changes to CapyMOA, you should follow these steps to set up an editable installation of CapyMOA, with development and documentation dependencies.

  1. Dependencies

    Follow the instructions above to install PyTorch, Java, and optionally a virtual environment.

  2. Pandoc

    Ensure that you have Pandoc installed on your system. If it’s not installed, you can install it by running the following command on

    sudo apt-get install -y pandoc

    sudo brew install pandoc

    Follow the instructions on the Pandoc website.

    conda install -c conda-forge pandoc

  3. Clone the Repository

    If you want to contribute to CapyMOA, you should clone the repository, install development dependencies, and install CapyMOA in editable mode.

    If you are intending to contribute to CapyMOA, consider making a fork of the repository and cloning your fork instead of the main repository. This way, you can push changes to your fork and create pull requests to the main repository.

    git clone https://github.com/adaptive-machine-learning/CapyMOA.git
# or clone via the SSH protocol (often preferred if you use SSH keys for git):
#   ``git clone with git@github.com:adaptive-machine-learning/CapyMOA.git``

  4. Install CapyMOA in Editable Mode

    To install CapyMOA in editable mode with development and documentation dependencies, navigate to the root of the repository and run:

    cd CapyMOA
uv sync --extra dev --extra doc --extra torch-cpu

    --extra torch-cpu installs CPU-only PyTorch wheels, resolved automatically via the pytorch-cpu index configured in pyproject.toml – no manual --index-url step needed. If you have a GPU and want CUDA-enabled PyTorch instead, use --extra torch in place of --extra torch-cpu (the two are mutually exclusive).

    cd CapyMOA
pip install --editable ".[dev,doc,torch]"

    The dev extra does not include torch – add it explicitly (as above) to run the whole test suite. On Linux, install the CPU build of PyTorch first if you do not want the CUDA packages – see the PyTorch note in Setup.

  5. Congratulations!

    You have successfully installed CapyMOA in editable mode.

    A number of utility scripts are defined in tasks.py to perform common tasks. You can list all available tasks by running:

    uv run invoke --list

    python -m invoke --list # or `invoke --list`

    Available tasks:

  commit                                     Commit changes using conventional
                                             commits.
  format (fmt)                               Format the code using ruff.
  lint                                       Lint the code using ruff.
  refresh-moa                                Replace the moa.jar file with the
                                             appropriate version.
  build.clean                                Clean all build artifacts.
  build.clean-moa                            Remove the moa.jar file.
  build.clean-stubs                          Remove the Java stubs.
  build.download-moa                         Download moa.jar from the web.
  build.stubs                                Build Java stubs using stubgenj.
  clean.build                                Clean all build artifacts.
  clean.docs                                 Remove the built documentation.
  clean.nb                                   Remove generated notebook
                                             artifacts (`.ipynb` files,
                                             execution side-effects).
  docs.build (docs)                          Build the documentation using
                                             Sphinx.
  docs.clean                                 Remove the built documentation.
  docs.nb                                    Execute notebooks and bake their
                                             outputs into their `.ipynb` files.
  test.all (test)                            Run all the tests.
  test.coverage-clean (test.cov-clean)       Clean coverage data.
  test.coverage-combine (test.cov-combine)   Combine coverage data from
                                             different sources.
  test.coverage-report (test.cov-report)     Generate coverage report.
  test.doctest                               Run tests defined in docstrings
                                             using pytest.
  test.nb                                    Execute notebooks and bake their
                                             outputs into their `.ipynb` files.
  test.pytest                                Run the tests using pytest.

    Each of these tasks can be run in the terminal through invoke <task>. If you installed with uv sync (and have not separately activated .venv), prefix every invocation with uv run instead – uv sync does not put .venv on PATH the way activating it does. Running the task to build documentation would look like this:

    uv run invoke docs.build

    invoke docs.build

    See the Contributing guide for more information on how to contribute to CapyMOA, including how to test PyTorch-optional code in Adding Tests.