Skip to content

Installation

Install Potato with pip on macOS, Windows, or Linux. Covers Python versions, virtual environments, optional extras, and upgrading from 2.7.1 or earlier.

Potato installs with pip. This guide covers the Python versions it supports, the optional extras, and the upgrade path from 2.7.1 or earlier.

Upgrading from 2.7.1 or earlier

Wheels up to 2.7.1 declared their package data with a single-level glob, so 27 templates stored in subdirectories never made it into the published package. If you installed with pip, solo mode's setup routes, the admin dashboard, judge calibration and the corpus map were all broken. Running from a git checkout was unaffected, which is why the test suite never caught it.

Version 2.8.0 fixes the packaging. It was reported and fixed in PR #164 by @0x6362.

bash
pip install --upgrade potato-annotation

Requirements

  • Python: 3.9 or higher
  • Operating System: macOS, Linux, or Windows
  • Memory: 512MB RAM minimum

Install via pip

The recommended way to install Potato:

bash
pip install potato-annotation

Optional extras

The default install pulls in no machine-learning stack. Add the extras you need:

bash
pip install 'potato-annotation[ai]'        # LLM endpoints
pip install 'potato-annotation[vision]'    # local vision models
pip install 'potato-annotation[db]'        # database data sources
pip install 'potato-annotation[mysql]'     # MySQL annotation storage (2.10.2+)
pip install 'potato-annotation[transcribe]'  # local transcription and diarization (2.9+)

vision is deliberately excluded from [all], because torch is a multi-gigabyte install and nothing in the default experience needs it. Model weights are a separate, explicit step:

bash
potato download-models --list
potato download-models mobile_sam

Nothing is bundled and nothing downloads unless you ask for it. For an air-gapped install, run the downloads on a connected machine and copy the directory across.

Install from source

For the latest development version:

bash
git clone https://github.com/davidjurgens/potato.git
cd potato
pip install -e .

Install specific version

To install a specific version:

bash
pip install potato-annotation==2.12.1

Verify installation

Check that Potato is installed correctly:

bash
potato --version

You should see the version, plus the commit when you are running from a checkout:

text
potato 2.12.1

Upgrade

To upgrade to the latest version:

bash
pip install --upgrade potato-annotation

Optional dependencies

Potato 2.12.1 declares these extras: ai, formats, viz, preview, mcp, agent, export, huggingface, publish, auth, langchain, fiftyone, s3, gcs, azure, wsi, saml, volumes, db, mysql, deploy, deploy-aws, deploy-openstack, hosting, vision, transcribe and decision. Pick the ones a task needs, or take all:

bash
# Database-backed data sources
pip install 'potato-annotation[db]'
 
# MySQL as the store for annotations (database: {type: mysql})
pip install 'potato-annotation[mysql]'
 
# What a coding agent needs: the MCP server plus browser rendering
pip install 'potato-annotation[agent]'
 
# Most extras. Left out: vision and decision, which pull torch, plus deploy-aws,
# deploy-openstack, fiftyone, s3, gcs, azure, wsi, saml and volumes
pip install 'potato-annotation[all]'

Troubleshooting

Permission errors

If you encounter permission errors, try:

bash
pip install --user potato-annotation

We recommend using a virtual environment:

bash
python -m venv potato-env
source potato-env/bin/activate  # On Windows: potato-env\Scripts\activate
pip install potato-annotation

Next Steps