Frequently Asked Questions

Potato (Portable Text Annotation Tool) is a free, open-source annotation tool for building labeled datasets. It covers text, image, audio, and video annotation, and a task is defined in a YAML configuration file.

Yes. Potato is free and open-source under the GNU General Public License v3.0 or later (GPL-3.0-or-later). You can use, modify, and redistribute it, including for commercial use, as long as derivative works stay under the GPL. Earlier releases used the PolyForm Shield license; Potato relicensed to GPL-3.0 in version 2.6. See the LICENSE file in the GitHub repository for the full text.

No coding is required. A task is defined in a YAML configuration file, and the Playground builds that file through a visual form.

Install via pip: `pip install potato-annotation`. Then run `potato start my_project -c config.yaml` to launch your annotation server. See our Quick Start guide for detailed instructions.

Potato requires Python 3.7 or higher. We recommend Python 3.10 or newer.

Run `pip install --upgrade potato-annotation`. Check the changelog at /blog for new features. Existing configs are forward-compatible, so a minor version update needs no migration.

Potato works in current versions of Chrome, Firefox, Safari, and Edge. The annotation interface is responsive and works on tablets, though a desktop is easier for tasks with many schemes.

Your data stays on your machine. Potato runs locally and never sends your data to external servers, which is why it ends up on sensitive material such as medical records and proprietary content.

Yes. Potato is self-hosted, so annotation data stays inside your own infrastructure. That is usually the condition a HIPAA or GDPR review turns on, though compliance also depends on how you run and secure the server.

Potato supports various input formats including plain text, JSON, JSONL, CSV, TSV, images (PNG, JPG, GIF, WebP), audio (MP3, WAV, OGG), and video files. Output can be exported to JSON, JSONL, CSV, and specialized formats like CoNLL, COCO, and HuggingFace datasets.

Potato ships 61 annotation types, including radio buttons (single choice), checkboxes (multi-select), Likert scales, text input, span highlighting, bounding boxes, polygons, pairwise comparison, and best-worst scaling. See the Showcase for worked examples.

Yes. A single annotation task can include any combination of annotation schemes. For example, you might have annotators highlight entities (span annotation), classify sentiment (radio buttons), and provide comments (text input) all on the same item.

Yes. Potato supports image classification with radio/checkbox labels, bounding box annotation for object detection, and polygon annotation for segmentation tasks.

Yes. Potato can display audio waveforms and video players alongside annotation controls. This is useful for transcription review, speaker diarization, emotion detection, and similar tasks.

Add a span annotation scheme in your config with the text to highlight. Annotators can select text spans and assign labels. See our NER and span annotation examples in the Showcase.

Yes. Potato supports custom CSS, custom HTML templates, and layout configuration via YAML. You can add custom headers, footers, instructions, and styling. See the layout customization docs for details.

Potato supports multiple annotators out of the box. Each annotator logs in with a unique ID, and their annotations are tracked separately. You can configure overlap to have multiple annotators label the same items for quality control.

Yes. Potato integrates with Prolific and Amazon Mechanical Turk. Annotators are redirected from the platform, complete tasks in Potato, and are returned with completion codes.

Potato computes agreement while the study runs and reports Krippendorff's alpha in the admin dashboard, so you can catch a poorly defined task before the budget is spent. You can also export the annotations and compute Cohen's kappa or another coefficient yourself.

Yes. You can add attention check items, configure required annotation overlap, and use the admin dashboard to monitor annotator progress and identify potential issues.

Common issues: 1) Check that your config.yaml is valid YAML syntax. 2) Ensure your data file exists and is properly formatted. 3) Check that the port (default 8000) isn't already in use. 4) Look at the terminal output for specific error messages.

Check that: 1) You clicked the Save/Submit button. 2) The output directory is writable. 3) All required fields are filled in. Check the browser console for JavaScript errors.

Delete the annotator's annotation file from the output directory. Their assignment will be regenerated on next login.

Join the Discord for questions, check GitHub Issues for known problems, or browse the documentation.