> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Import Labels (Curation)
Label ingestion lets you store annotation data as sidecar files alongside your files in a cloud storage folder. When a folder is configured for label ingestion, Encord automatically detects sidecar files during bucket scans, pairs them with their corresponding data files, and ingests their contents as labels against a chosen Ontology.
## Input Formats
Encord supports two input formats for label ingestion:
* **Encord (JSON sidecars)** — pairs each data file with a JSON sidecar file using a configurable filename suffix.
* **YOLO (.txt sidecars)** — pairs each data file with a YOLO-format `.txt` sidecar file using file path patterns, and maps YOLO class numbers to ontology classes.
The input format cannot be changed after label ingestion is enabled on a folder.
When using the Encord format, configure the **Sidecar suffix** field. Encord pairs each data file with a label file that shares the same name plus the suffix you specify.
For example, with the default suffix, `image001.jpg` pairs with `image001.jpg.encord.json`.
The suffix must be between 1 and 128 characters.
When using the YOLO format, configure the following fields:
* **Image and Label File Patterns**: Use the Image file pattern and Label file pattern fields to define how Encord pairs image files with their corresponding YOLO label files. Both patterns use a shared `{name}` placeholder as the capture group. The value matched by `{name}` in the image pattern must match the value in the label pattern for the two files to be paired. Both patterns must use the same placeholders.
* **External ID Namespace**: The External ID namespace field determines which namespace Encord reads class numbers from when mapping YOLO class numbers to ontology classes. Encord automatically selects a namespace when you choose an Ontology. It prefers a namespace named `YOLO` (case-insensitive), or falls back to the first available namespace alphabetically. You can unlock the namespace selector to choose a different namespace if needed.
If the selected Ontology has no external IDs on its classes, the namespace selector is unavailable and class numbers must be entered manually in the class map.
The **Class numbers** editor maps each YOLO class number to an Ontology class. Encord pre-fills class numbers from the external IDs on the selected ontology's classes under the chosen namespace. You can override individual entries by unlocking the relevant row.
The following Ontology object shapes are supported for YOLO label ingestion:
* Bounding box
* Polygon
* Rotatable bounding box
At least one class must be mapped to a YOLO class number. Each YOLO class number can only map to one ontology class. Class numbers must be non-negative integers.
If the selected Ontology has no bounding-box, polygon, or rotatable-box objects, Encord displays a warning and you must select a different Ontology.
## How it Works
During each scheduled bucket scan, Encord classifies every file in the folder. Files whose names match the configured suffix are identified as label sidecars and excluded from the data file list. Each sidecar is paired with its corresponding data file, and the label payload is downloaded, validated against the Ontology, and written to the database.
Under the hood, enabling label ingestion provisions labels linked to the Folder and the chosen Ontology.
The ingestion pipeline using a sidecar file:
1. **Labels check**: If an existing sidecar file matches the last ingestion skip (no change).
2. **Download sidecar**: Sidecar files are imported from cloud storage (max 300 MB).
Labels are imported as `ground truth` labels.
3. **UUID substitution**: Placeholder UUIDs sent by the SDK are replaced with server-allocated values.
4. **Ontology resolution**: The specified Ontology is loaded and Encord converts the payload into the Ontology's label format.
5. **Label write**: Labels appear on the data units.
If a sidecar is removed from the bucket, the corresponding label are removed from the data unit.
## Configuration
When creating or editing a Cloud-Synced folder:
1. Toggle **Label ingestion** on.
2. Set the **file suffix** that marks a file as a label sidecar (default: `.labels.json`).
3. Select the *Ontology* to validate and store labels against.
Once saved, subsequent scans begin ingesting labels matching sidecars.
The Ontology is fixed when you enable label ingestion and cannot be changed. To use a different Ontology, delete the label ingestion configuration and reconfigure the folder. Existing ingested labels are preserved, but new sidecars will ingest under the new Ontology only after reconfiguration.
### Configuration Options
| Option | Default | Description |
| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Input Format | Encord (JSON) | Choose between **Encord (JSON sidecars)** or **YOLO (.txt sidecars)**. **Cannot be changed after label ingestion is enabled.** |
| Suffix | `.labels.json` | (Encord format only) File suffix that identifies a sidecar. Any bucket key ending in this string is treated as a label file; the paired data key is the full key with the suffix removed. |
| Ontology | (required) | The Ontology used to validate ingested annotations. **Cannot be changed after label ingestion is enabled.** |
| Paused | `false` | When paused, sidecars are classified and excluded from data ingestion but are not downloaded or ingested. No new labels are written. Existing labels are preserved. |
## File Pairing
Label sidecar files must conform to the Encord label row format. The same schema accepted by the [SDK](/sdk-documentation/sdk-labels/sdk-import-labels-annotations-visual).
Maximum sidecar size: **300 MB** (matching the editor HTTP save limit).
Files are paired by stripping the suffix from the sidecar key to derive the data key.
Example with suffix `.labels.json`:
| Data file | Label sidecar |
| ---------------------- | ---------------------------------- |
| `dataset/image001.jpg` | `dataset/image001.jpg.labels.json` |
| `videos/clip_42.mp4` | `videos/clip_42.mp4.labels.json` |
| `scans/ct_scan.dcm` | `scans/ct_scan.dcm.labels.json` |
## Pausing and Resuming
Pausing stops new sidecars from being downloaded and ingested without removing existing labels. This is the recommended way to temporarily halt label ingestion. For example, while updating your sidecar generation pipeline.
To pause or resume: **Folder details** > **Label ingestion** > **Pause / Resume**.
## Disabling Label Ingestion
Deleting the label ingestion configuration removes the config from the folder. Already-ingested labels are preserved. No new sidecars are picked up after deletion.
To disable: **Folder details > Label ingestion > Delete (trash icon)** > Confirm.
## Supported Data Types
Label sidecars can be paired with any data type supported by cloud-synced folders:
* Images
* Videos
* Audio
* Text
* PDFs
* Time series