Release candidate

Use a separate virtual environment for the candidate. Once 4.0.0rc2 is published on PyPI, install that exact version:

python -m pip install "labelimgplusplus==4.0.0rc2"
labelimgpp

labelimgplusplus is an equivalent command. The older labelImgPlusPlus command still works but emits a deprecation warning. The explicit version pin selects this prerelease without --pre. Before publication, use the candidate checkout or a matching CI wheel instead; an unpublished version cannot be installed from PyPI.

Optional features can be installed together:

python -m pip install "labelimgplusplus[sam,video]==4.0.0rc2"

For the latest stable release instead, use a separate environment and python -m pip install labelimgplusplus. Its behavior and Python/Qt baseline follow that stable version, not this candidate.

PyQt6 candidate from source

Clone the immutable v4.0.0rc2 tag and run the install from the repository root. Git and Python 3.10–3.13 are required. Before the tag is published, use the existing candidate checkout or a matching CI artifact; the tag-based commands below become available at release time.

Linux and macOS:

git clone --branch v4.0.0rc2 https://github.com/abhiksark/labelImg-plus-plus.git
cd labelImg-plus-plus
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
labelimgpp

Windows PowerShell, using Python 3.13:

git clone --branch v4.0.0rc2 https://github.com/abhiksark/labelImg-plus-plus.git
Set-Location labelImg-plus-plus
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\labelimgpp.exe

Using the virtual environment’s executables directly avoids changing PowerShell’s script execution policy.

From the checkout, install optional features with the same environment’s Python so the installed extras and application come from the same source:

python -m pip install -e ".[sam]"        # Smart Select
python -m pip install -e ".[video]"      # Smart Video
python -m pip install -e ".[sam,video]"  # Both

On Windows, substitute .\.venv\Scripts\python.exe for python unless the environment is activated. Both extras share headless OpenCV. The base application leaves optional inference and video libraries unloaded until needed. See the optional-dependency guide for supported versions and separately managed SAM 2 dependencies.

Qt and asset troubleshooting

Pip installs PyQt6 automatically; Qt development tools and an RCC resource compiler are not required. Icons, translations, and licenses are ordinary package data under libs/assets.

Linux still needs a desktop session and Qt’s runtime system libraries. On a minimal Ubuntu/Debian installation, an xcb platform-plugin error may mean missing X11/xcb libraries, including libxcb-cursor0. Follow Qt’s Linux runtime requirements for your distribution. QT_DEBUG_PLUGINS=1 labelimgpp exposes the actual missing library; do not install a second OpenCV distribution to repair Qt.

Check packaged assets without opening the annotation workspace:

labelimgpp --verify-assets

Expected output: Verified 44 icons, 4 string bundles, and 1 license. From source, python3 labelImgPlusPlus.py --verify-assets performs the same check. The command aliases also support it.

Native executables

Candidate CI builds Linux x86-64, Windows x86-64, and macOS arm64 executables from one PyInstaller definition. Linux uses Ubuntu 22.04 as its glibc baseline. Each build checks packaged assets and startup outside the checkout.

Published candidate downloads belong to the v4.0.0rc2 GitHub prerelease. Before publication, open the successful candidate run for the exact commit under GitHub Actions and select the matching platform artifact; GitHub may require sign-in. Extract the complete artifact before launching it. A CI artifact is not a published release, and one artifact’s architecture is not a claim of universal platform support.

Native builds include base annotation and the plugin host, not SAM/video dependencies or third-party plugins. Use the Python package with extras for those features. See the build and candidate-qualification guide.

Single-click Box or Polygon

Install the sam extra, then choose Smart Select (S) on the rail or Tools → SAM Segment. MobileSAM runs through ONNX Runtime without requiring PyTorch. Enabling it with an image loaded starts preparation; the default encoder/decoder pair is downloaded if absent and SHA256-verified. Further clicks on that image reuse its embedding.

Choose an output in the canvas control:

• Box: tight pixel bounds of the largest selected mask component.

• Polygon: an editable, simplified contour of that component.

Both currently use the same mask-processing path. A usable polygon is still required internally even for Box output; a direct, polygon-free Box pipeline is not implemented. Box bounds come from the full component, not the simplified polygon’s vertices.

Every provisional result takes one confirmation. The class picker opens beside the outline: choose or type a class and press Enter to keep the result, or press Esc to discard it and try another point. Fixed/default labels and established repeat-class sessions have no class to enter, so they confirm the outline instead, for example with Use outline as car (Enter), or discard it with Try again (Esc); they do not skip that confirmation. The confirmed result is one undo step; Smart Select stays active and the output choice persists between sessions.

The Smart Select guide shows Polygon output and model configuration. Custom encoder/decoder files must be a compatible matched MobileSAM ONNX export, not arbitrary SAM models. Only load models from trusted sources. In video documents, Smart Select works on the paused frame; it is not temporal tracking.

Portable propagation and optional SAM 2

The OpenCV backend propagates rectangles, polygons, and associated keypoints. It displays cancellable preview-only progress, protects manual anchors encountered in either direction, and commits pending tracker observations and explicit gaps in one atomic undo step. Editing generated geometry creates a manual correction; bounded neighboring regeneration is a separate undoable change.

Tools → SAM Settings… selects Auto, OpenCV, or SAM 2. Auto uses SAM 2 only when its Linux/CUDA environment, compatible Torch/torchvision, source-installed SAM 2, checkpoint, and matching configuration are available; otherwise it uses OpenCV. The config must reside inside the installed sam2 package directory. Explicitly selecting unavailable SAM 2 reports the missing requirement rather than silently falling back.

labelImg++ does not bundle or download Torch, SAM 2, checkpoints, or configs. They are not part of its extras. Follow the optional-dependency and Smart Video guides rather than installing them into the base environment indiscriminately.

Gallery and Objects inspector

The fixed tool rail, compact command bar, and collapsible Objects/Files inspector keep editing beside the canvas. Search, rename, select, or hide annotations in one Objects view; its context card follows the active tool, selected object, or pending video review. Clicking nested annotations selects the smallest containing shape.

Image Gallery is embedded in the workspace and previews all five annotation formats. Gray borders mean no labels, blue means labeled, and green means verified where the format preserves that state. Boxes use corner markers; polygons use outlines. S/M/L/XL presets and a slider control thumbnail size.

Video Gallery becomes a track/frame overview. Distinct retains manual, verified, boundary, and transition events and samples ordinary frames at most twice per second, with bounded visual-change refinement. Annotated and Pending expose stored annotations and outstanding review work. Selecting a track narrows the overview; export readiness and pending counts remain visible.

Themes, display, and editing

Light and dark themes, Feather icons, and high-DPI scaling serve the same workspace. Ctrl+Shift+T toggles themes and persists the choice. Brightness controls help inspect dark or light images without changing source media. See the theme guide for light/dark screenshots. Annotation creation and editing support undo/redo.

Ultralytics export

Tools → Export Ultralytics Dataset… builds a YOLO detection dataset with images/{train,val,test}, matching labels, and data.yaml. Choose deterministic split ratios and image copies or absolute local symlinks. The destination must be new or empty; it is published only after export succeeds. Polygons become enclosing boxes; this is not a segmentation or pose export. See the Ultralytics export guide for layout and data-preservation limits.

Installed Python plugins

Install trusted command plugins as separate Python distributions, then review and enable them in Tools → Plugins… and restart. The versioned public API provides host-owned actions, namespaced shortcuts/settings, bounded background work, read-only document access, and diagnostics. Plugins do not need changes to labelImg++ source.

LABELIMGPP_DISABLE_PLUGINS=1 disables plugins for recovery. Reset All also clears plugin enablement and configuration; see Configuration and recovery. The plugin authoring guide describes the public API and PyQt6 compatibility boundary.

Classes and command-line paths

The bundled defaults are in libs/data/predefined_classes.txt. Keep custom labels in a separate UTF-8 file, one class per line:

cat
dog
person
car
bicycle

Pass an image/directory, optional class file, and optional save directory:

labelimgpp /path/to/images /path/to/classes.txt /path/to/labels

The first path can also be a video or .labelimgpp.sqlite project. Default labels and repeat-last-class controls reduce repeated class entry; they do not skip Smart Select outline confirmation.

Reset settings

Application menu → File → Reset All asks for confirmation, clears preferences, and restarts the application. It removes the save directory, format, theme, recents, layout, shortcut overrides, and plugin activation/configuration settings—not annotation files. Back up settings first if you need to retain those choices.

For manual recovery, quit the application first so closing it cannot rewrite the settings you removed. On Linux/macOS:

rm ~/.labelImgSettings.json

On Windows PowerShell:

Remove-Item "$HOME\.labelImgSettings.json"

Media credits

The cat photograph is Cat November 2010-1a by Alvesgaspar, licensed CC BY-SA 3.0. The workspace, inline-class, and Smart Select screenshots resize that photograph and add annotation/UI overlays; those screenshot adaptations are also distributed under CC BY-SA 3.0. This does not change the application’s MIT license.

The video screenshot uses Samplelib’s 10-second MP4 sample, offered there without license restrictions, with annotations and review controls added by labelImg++. Screenshots demonstrate actual application states, not detection or tracking accuracy benchmarks.