# Installation

Source: https://www.potatoannotator.com/docs/getting-started/installation

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](https://github.com/davidjurgens/potato/pull/164) by [@0x6362](https://github.com/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.11.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:

```
potato 2.11.1
```

## Upgrade

To upgrade to the latest version:

```bash
pip install --upgrade potato-annotation
```

## Optional dependencies

Potato 2.11.1 declares these extras: `ai`, `formats`, `viz`, `preview`, `mcp`, `agent`, `export`, `huggingface`, `publish`, `auth`, `langchain`, `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]'

# Every extra except vision and decision, which stay out because torch is multi-gigabyte
pip install 'potato-annotation[all]'
```

## Troubleshooting

### Permission errors

If you encounter permission errors, try:

```bash
pip install --user potato-annotation
```

### Virtual environment (recommended)

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

- Follow the [Quick Start](/docs/getting-started/quick-start) guide
- Learn about [Configuration Basics](/docs/getting-started/configuration-basics)
- Put a task in front of annotators with [Running Potato Locally or in the Cloud](/docs/deployment/quick-deploy)