Skip to main content

​
Prerequisites

Before installing Archeo-Cluster, make sure you have:
  • Python 3.11 or later — Archeo-Cluster requires Python 3.11+. Check your version with python --version.
  • uv — The recommended package manager for Archeo-Cluster. Install it from docs.astral.sh/uv.
uv handles virtual environment creation and dependency locking automatically. You do not need to create a virtual environment manually.

​
Install Archeo-Cluster

1

Clone the repository

git clone https://github.com/keviingarciah/archeo-cluster.git
cd archeo-cluster
2

Install dependencies

Run uv sync to install all dependencies into an isolated virtual environment:
uv sync
uv reads pyproject.toml and installs all required packages including NumPy, OpenCV, pandas, scikit-learn, matplotlib, and Typer.
3

Verify the installation

Confirm the CLI is available using either of these commands:
./run-cli --help
You should see the Archeo-Cluster help output listing available commands: detect, cluster, analyze, pipeline, and sessions.

​
Dev install

If you plan to contribute or run the test suite, install the development dependencies: 
uv sync --extra dev
This adds pytest, ruff, mypy, pre-commit, and type stubs to your environment. Then set up the pre-commit hooks: 
uv run pre-commit install
Pre-commit hooks run ruff formatting and linting checks automatically on every commit.

​
Running make commands

The project includes a Makefile with common development tasks:
CommandDescription
make installInstall dependencies with uv sync --extra dev
make testRun the full test suite with pytest
make lintRun ruff and mypy on src/ and tests/
make formatFormat and auto-fix code with ruff
make checkRun lint and test together
# Run tests
make test

# Lint and type-check
make lint

# Format code
make format

# Run all checks
make check
Use make check before opening a pull request to run both linting and the test suite in one step.

​
Troubleshooting

If ./run-cli fails with a permission error, make the script executable: chmod +x run-cli
If uv is not found, install it following the uv installation guide and ensure it is on your PATH. If you see import errors for cv2 or other packages, confirm you are running commands with uv run or that your shell has activated the uv-managed virtual environment.

Build docs developers (and LLMs) love

Get started for freeTalk to us