Installation

Installation#

Requirements#

Python 3.10 or newer. Older versions are not supported.
OpenCV (>= 4.5.0). On modern Python this comes from the opencv-python wheel; no system OpenCV needed.
A recent scientific-Python stack — NumPy, SciPy, pandas, matplotlib, scikit-image, scikit-learn, Pillow, seaborn, plotly. All pulled in automatically by pip install.

Install from PyPI#

pip install amfora

PyPI project page: pypi.org/project/amfora. This is the recommended path for users — you get a stable, tested release.

Install from source#

If you want the latest unreleased changes, or you’re developing against the package, install from the GitHub repo instead:

git clone https://github.com/aleciaco/AMFOrA_public.git
cd AMFOrA_public
pip install -e .

The -e flag installs the package in editable mode — changes to the source are picked up immediately without reinstalling. Drop the -e if you just want to use the source-tip without developing it.

Recommended: use a fresh virtual environment#

Create an isolated environment so AMFOrA’s dependencies don’t conflict with anything else on your system. With conda:

conda create -n amfora python=3.12 -y
conda activate amfora
pip install amfora

With venv (built into Python):

python -m venv .venv
source .venv/bin/activate   # macOS / Linux
# .venv\Scripts\activate    # Windows
pip install amfora

Verify the install#

import amfora
print(amfora.__version__)
print(amfora.analyze_single_sherd)

If both lines run without an ImportError, you’re set.

Development install#

If you intend to contribute (run the test suite, lint with ruff, build the docs locally), install the optional dev extras:

pip install -e ".[dev]"

That pulls in pytest, pytest-cov, ruff, jupyter-book, and sphinx-autodoc-typehints. See Contributing for the development workflow.

Troubleshooting installation#

ERROR: Package 'amfora' requires a different Python: 3.x not in '>=3.10' — your active interpreter is too old. Create a fresh env on Python 3.10+ as shown above.
ModuleNotFoundError: No module named 'cv2' after install — the opencv-python wheel sometimes fails silently on unusual platforms. Try pip install opencv-python directly to see the real error.
cv2.error: ... validateParameters on bright pastes — you’re on a version of AMFOrA before the OpenCV 4.10+ compatibility fix. Update to v1.0.0 or later.

For runtime issues (no features detected, suspicious counts), see Troubleshooting.