# Importing a Project from brat, doccano, Prodigy, CoNLL or a QDA Tool

Source: https://www.potatoannotator.com/docs/tools/importing-projects

**Since Potato 2.9, one command turns a brat, doccano, Prodigy, CoNLL-2003, CoNLL-U or REFI-QDA `.qdpx` export into a runnable Potato project.** The importer writes a data file, a `config.yaml` with the right annotation scheme already declared, and a README. The same command reads 15 computer-vision formats, covered in [Computer Vision Formats](/docs/vision-spatial/cv-formats).

```bash
potato import -i <your-export> -o my-project
potato start my-project/config.yaml -p 8000
```

The format is detected from the file. Pass `--input-format` only when detection cannot decide; it refuses to guess rather than produce a silently wrong import. `potato import --list-formats` lists everything supported.

## Pre-annotations

Existing annotations arrive as a starting point. Every annotator sees them, and they are stored only once someone saves. An item nobody opens exports as **empty**, not as agreement nobody gave, which keeps machine output and old labels from being counted as new human work.

## Supported text and qualitative formats

| Coming from | Format | Notes |
|---|---|---|
| [brat](https://brat.nlplab.org/) | `.ann` + `.txt` | Directory of file pairs. Discontinuous mentions survive; relations and events do not yet |
| [doccano](https://github.com/doccano/doccano) | JSONL | Sequence labelling and document classification |
| [Prodigy](https://prodi.gy/) | `db-out` JSONL | Rejected and ignored tasks are dropped by default |
| CoNLL corpora | CoNLL-2003, CoNLL-U | Column format or 10-column UD |
| NVivo, ATLAS.ti, MAXQDA, Quirkos, QDA Miner | REFI-QDA `.qdpx` | Codebook hierarchy, codings and annotator identity |

### brat

Point at the directory, and the importer pairs each `.ann` with its `.txt`:

```bash
potato import -i ./my-corpus/ -o potato-project
```

brat offsets are Unicode code points with an exclusive end, which is Potato's convention too, so nothing is converted. Discontinuous mentions keep their extra fragments. Relations (`R`) and events (`E`) are listed in the warnings rather than imported, because they reference `T` ids that must be resolved to Potato span ids first, and resolving them wrongly would attach a relation to the wrong span without telling you.

### doccano

```bash
potato import -i export.jsonl -o potato-project
```

Span entries are read in all three shapes doccano has emitted across versions (`[start, end, label]`, `start_offset`/`end_offset`, and `start`/`end`), so an older export works. Document categories become their own multiselect scheme.

### Prodigy

```bash
potato import -i db-out.jsonl -o potato-project
```

Tasks answered `reject` or `ignore` are not imported by default. A rejection is a person saying the annotation is wrong, and importing it as approved work turns that into positive signal. Pass `--prodigy-keep-rejected` to bring them in anyway. The `answer` field becomes a radio scheme, so the verdict survives either way.

### CoNLL

```bash
potato import -i eng.train -o potato-project
```

[CoNLL](https://universaldependencies.org/format.html) records tokens and their tags, never where they sat in a string, so the text is reconstructed before any character offset exists. How faithfully depends on what the file kept:

- **CoNLL-U with `# text =`** is exact, because the sentence string is in the file.
- **CoNLL-U without it** is rebuilt from tokens. `SpaceAfter=No` is honoured.
- **CoNLL-2003** joins tokens with single spaces. The format records no spacing, so `"Dr. Smith"` and `"Dr.  Smith"` produce the same file.

`--conll-document-unit` decides what counts as one item: `auto` (the default) follows `-DOCSTART-` and `# newdoc` markers and falls back to one item per sentence.

### REFI-QDA (`.qdpx`)

`.qdpx` is the interchange format NVivo, ATLAS.ti, MAXQDA, Quirkos and QDA Miner all read and write.

```bash
potato import -i project.qdpx -o potato-project
```

The codebook comes across with its hierarchy, descriptions and colours, along with the codings and which annotator made each one. Potato also exports `.qdpx`, so a coded project can go back to the QDA tool it came from. See [QDA Mode](/docs/qda/qda-mode).

REFI-QDA 1.5 defines a selection by its first and last character, which makes the end position **inclusive** where Potato's is exclusive. Exporting tools have not all read the spec the same way, so the importer measures both readings against the source text, uses the one that fits, and warns when a file contradicts the spec. `--qdpx-end-position inclusive|exclusive` forces a reading.

ATLAS.ti keeps only one level of subcode. Export with `--option flatten_subcodes=true` to re-parent every code to the top level under a `Parent > Child` name, which loses the tree but keeps every code readable.

## Checking an import

Because imported annotations are pre-annotations, an import is hard to check end to end without opening every item. `--seed-user` writes them as one annotator's saved work, so you can export straight away and diff against the source:

```bash
potato import -i ./corpus/ -o p --seed-user check
```

`--seed-user` creates an annotator who never annotated anything. Use it only to verify the round trip, and keep that user out of agreement and adjudication.

## Known gaps

Each of these produces a warning on import:

- **brat relations and events** are reported, not imported.
- **Sub-token spans through CoNLL.** A span covering `Paris` inside the token `Paris.` comes back as the whole token.
- **Whitespace through CoNLL-2003**, which the format does not record.
- **Non-text QDA sources.** Picture, PDF, audio and video sources in a `.qdpx` are not imported yet; text sources are.
- **Uncoded selections in a `.qdpx`**, which have no code to import. They are counted in the warnings.

## Related

- [Computer Vision Formats](/docs/vision-spatial/cv-formats): the 15 CV importers
- [Export Formats](/docs/features/export-formats): going the other way
- [QDA Mode](/docs/qda/qda-mode): what Potato does once a qualitative project is in
- [Annotation Tools Compared](/docs/guides/annotation-tools-compared)

For implementation details, see the [source documentation](https://github.com/davidjurgens/potato/blob/master/docs/guides/migrating-into-potato.md).