JSON2YOLO converts detection annotations, and the project now points you elsewhere

The repository is now a pointer to the main package

The important update sits in a callout near the top of the README. The JSON2YOLO project is now integrated into the main Ultralytics package, the standalone scripts in this repository are no longer being actively updated, and the latest functionality is the `convert_coco()` method described in the updated data converter documentation. That makes this repository a legacy artefact with a maintained successor, and it changes what an article about it should say. The original purpose remains: a toolkit to convert datasets in JSON format, particularly those following the COCO standards, into the YOLO format, which is widely recognized for its efficiency in real-time object detection tasks. The code is described as flexible and designed to run across Linux, macOS and Windows.

The maintained path is a pip install and a function call

For new work the documented route is the package, not this repository. You install ultralytics:

pip install ultralytics

and then call the converter:

from ultralytics.data.converter import convert_coco

convert_coco(
    labels_dir="path/to/annotations",
    save_dir="path/to/output_dir",
    use_segments=False,
    use_keypoints=True,
)

The method processes COCO detection, segmentation and keypoint annotations and saves YOLO labels in the specified directory. The two boolean flags are what select the task, with `use_segments` for segmentation and `use_keypoints` for pose. For the standalone path the environment is Python 3.8 or later with the dependencies installed from the requirements file, which lists numpy, opencv-python at 4.6.0 or newer, pandas, Pillow, pycocotools, pyYAML, requests and tqdm. The opencv and pycocotools entries tell you what the conversion actually does, which is to read and rasterise image and annotation data rather than to shuffle JSON around.

The legacy script has one command per shape of output

The standalone script is still there for existing workflows, and its flags mirror the three output types. Without a flag you get detection labels, with `--use-segments` you get segmentation labels, and with `--use-keypoints` you get pose labels:

python general_json2yolo.py --source COCO --json-dir path/to/annotations --save-dir yolo_out
python general_json2yolo.py --source COCO --json-dir path/to/annotations --use-segments --save-dir yolo_seg
python general_json2yolo.py --source COCO --json-dir path/to/annotations --use-keypoints --save-dir yolo_pose

The `--source` argument is the part that tells you how much shape the input has. The source list in the project description covers COCO, LabelMe, Labelbox, VoTT, INFOLKS and ATH annotations, and the notes spell out the difference in expectations. COCO input should be a directory containing `*.json` files with standard `images`, `annotations` and `categories` keys. LabelMe input should be a directory containing one JSON file per image. Labelbox exports can be JSON lists or newline-delimited JSON, and bounding box objects are converted while mask-only objects are skipped with a warning. A separate script exists for Labelbox in the repository.

The output directory is destroyed on each run

There is one behaviour in the notes that will bite somebody if it is not read, and it is that the `--save-dir` controls the output directory and is deleted and recreated on each run. The tool does not merge into an existing directory. The resulting layout follows the Ultralytics YOLO dataset structure, with a `data.yaml`, an `images/` directory and a `labels/` directory, and the comment on the yaml explains that it is for LabelMe only, because COCO writes one yaml file named after the input json stem containing the class names. There is also a detail about images: they are copied for LabelMe when the `imagePath` in the JSON points at an existing local file next to the JSON. So for LabelMe the conversion is self-contained, while for COCO the images are expected to already be in place and only the labels are produced.

The licence question comes up before the code does

The licensing section offers two options and it is worth reading it as a decision input rather than boilerplate. The AGPL-3.0 licence is described as ideal for students and enthusiasts, an OSI-approved open source licence that promotes collaboration and knowledge sharing, with the details in the LICENSE file. The Enterprise Licence is described as designed for commercial use, permitting integration of Ultralytics software and AI models into commercial products and services, bypassing the open source requirements of AGPL-3.0, with commercial inquiries directed to the Ultralytics licensing page. The repository itself is AGPL-3.0. If you are building a product that trains or serves models, that choice determines what you can ship, and it is a conversation to have before you wire the converter into a pipeline.

A small repository with a long tail of formats

The repository is small, with the two scripts, a `utils.py`, the requirements file, a `tests/` directory, an AGENTS.md and a CLAUDE.md. The interesting part is the range of input formats in the source list, since a converter that only handles COCO is a commodity and one that handles COCO, LabelMe, Labelbox, VoTT, INFOLKS and ATH is doing real work, because each of those annotation schemas describes geometry in a different way. The release history confirms the age. There are two tags, v0 and v1, both from 2019-05-11, and the last push to the main branch was on 2026-10-06, which is the repository being kept alive as a pointer rather than as a product. The project asks for a citation with a Zenodo DOI, and the contribution guide lives in the Ultralytics documentation rather than in the repository.

Editorial conclusion

Adopt the convert_coco() method in the main ultralytics package if you need this conversion today, since that is where the project has moved and where the fixes will land. Do not start a new integration against the standalone scripts in this repository, because the README states they are no longer being actively updated. Verify first which annotation source you have, since the input expectations differ per source, and that the output directory you pass is one you can afford to have deleted and recreated, because the tool deletes and recreates it on each run.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. ultralytics/JSON2YOLO on GitHub