# Quick Start

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

Get Potato running in just a few steps. This guide will have you annotating data in under 5 minutes.

## Prerequisites

- Python 3.7 or higher
- `pip` package manager
- A terminal

## Installation

We recommend installing Potato into a virtual environment so it doesn't collide with your system Python:

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

Verify the install:

```bash
python -c "import potato; print(potato.__version__)"
```

You should see a version like `2.4.4` printed. Potato does not expose a `potato --version` flag — the Python one-liner is the canonical check.

## Create Your First Project

### 1. Create a project directory

```bash
mkdir my-annotation-task
cd my-annotation-task
```

### 2. Create your data file

Create a `data` folder and a file called `data.json` inside it:

```bash
mkdir data
```

```json
[
  {"id": "1", "text": "I love this product! It's amazing."},
  {"id": "2", "text": "This is the worst experience ever."},
  {"id": "3", "text": "It's okay, nothing special."}
]
```

Potato also accepts `.jsonl` (one JSON object per line), `.csv`, and `.tsv` for `data_files` — just point at a file with the matching extension.

### 3. Create your configuration

Create a file called `config.yaml` in your project directory:

> **Path sandbox**: Any relative paths inside your config (like `data_files` or `output_annotation_dir`) are resolved against `task_dir` and must stay inside it. Paths that resolve outside `task_dir` are rejected to prevent path traversal.

```yaml
annotation_task_name: "Sentiment Analysis"

# All relative paths below are resolved against task_dir.
task_dir: "."

# Data configuration
data_files:
  - "data/data.json"

# Tell Potato which fields in each record to use.
# id_key = unique identifier; text_key = the text shown to annotators.
item_properties:
  id_key: id
  text_key: text

# Where per-user annotation state is stored (relative to task_dir).
output_annotation_dir: "annotation_output/"
export_annotation_format: "json"

# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"   # required for radio schemes
    labels:
      - Positive
      - Negative
      - Neutral

# Skip password authentication so anyone can log in with just a username.
require_password: false
```

> **Tip**: You can validate your config without launching the full server using the [Preview CLI](/docs/tools/preview-cli). It's the fastest way to catch typos before you start annotating.

### 4. Start the server

```bash
potato start config.yaml -p 8000
```

Equivalent long form:

```bash
python -m potato start config.yaml -p 8000
```

If port 8000 is already in use, pick another: `potato start config.yaml -p 8001`.

To stop the server, press `Ctrl+C` in the terminal.

> **Faster first run**: Add `--debug` to bypass the login screen entirely while you're experimenting: `potato start config.yaml --debug`.

### 5. Open your browser

Navigate to [http://localhost:8000](http://localhost:8000). You'll see a login screen with a single **username** field — type anything (e.g. `alice`) and click **Continue**. You're now annotating.

Each time you select a label and click **Next**, your annotation is saved automatically. There's no separate "save" button.

## Where Your Annotations Go

Potato writes per-user state as you annotate:

```
my-annotation-task/
├── config.yaml
├── data/
│   └── data.json
└── annotation_output/              # created automatically
    └── alice/
        └── user_state.json         # one folder per username
```

`user_state.json` holds the full annotation state for that user. To produce a consolidated, flat file across all annotators, use Potato's export CLI — see the [export documentation](https://github.com/davidjurgens/potato/blob/main/docs/data_formats.md) for details.

## Common First-Run Issues

- **`Address already in use`** — port 8000 is taken. Use `-p 8001` (or any free port).
- **`KeyError: 'description'`** — a radio (or similar) scheme is missing its required `description` field. Every scheme needs one.
- **`Path ... is outside the task directory`** — a `data_files` or `output_annotation_dir` path escapes `task_dir`. Keep everything inside the project folder, or set `task_dir` to an absolute path that contains them.
- **Login page shows a password field** — you forgot `require_password: false`, or you're on a cached browser tab. Restart the server and hard-refresh.

## What's Next?

- Learn about [Configuration Basics](/docs/getting-started/configuration-basics) for more options
- Explore different [Annotation Types](/docs/annotation-types/radio-multiselect)
- Set up [User Management](/docs/core-concepts/user-management) for your team
- Discover [What's New in v2](/docs/getting-started/whats-new-v2) including AI support and active learning

## Tools & Utilities

Once you're comfortable with the basics, check out these helpful tools:

- [Preview CLI](/docs/tools/preview-cli) - Validate configurations without running the server
- [Debugging Guide](/docs/tools/debugging-guide) - Debug flags and troubleshooting tips
- [User Simulator](/docs/tools/simulator) - Test with simulated annotators