Skip to main content

Simple tool to manually label images in disctinct categories.

Project description


PyPI version Travis CI status License: GPL v3

Graphical tool to manually label images in distinct categories to build training datasets. Simply pass a list of categories, a directory containing images and start labelling. Supports multiple users, reconciliation and keyboard bindings to label even faster!



Install with pip

Simplabel is on PyPI so it can be installed with pip

pip install simplabel

Install from source

Clone the repository to your computer

git clone

and install with pip

cd Simplabel
pip install .


Quick start

Simplabel can be started from the command line without any argument:


You will be prompted to select a directory containing images to label. Add labels with the '+' button and start labeling. Number keys correspond to labels and can be used instead.

The target directory and/or labels can also be passed directly from the command line:

simplabel --labels dog cat bird --directory path/to/image/directory

After the first use, labels are stored in labels.pkl and the --labels argument is ignored.

Command line arguments

  • -d, --directory <PATH/TO/DIRECTORY> sets the directory to search for images and save labels to. Defaults to the current working directory.
  • -l, --labels <label1 label2 label3 ...> sets the categories for the labelling task. Only passed on the first use in a given directory.
  • -u, --user <USERNAME> sets the username. Defaults to the OS login name if none is passed.
  • -r, --redundant does not display other labelers selections for independent labelling. Reconciliation and Make Master are unavailable in this mode.
  • -v, --verbose increases the verbosity level.
  • --remove-label <LABEL> tries to safely remove a label from the list saved in labels.pkl (must also pass -d)
  • --reset-lock overrides the lock preventing the same username from being used multiple times simultaneously.
  • --delete-all removes all files created by simplabel in the directory (must also pass -d)


The app relies on the filesystem to save each user's selection and display other user's selections. It works best if the working directory is on a shared drive or in a synced folder (Dropbox, Onedrive...). The Reconcile workflow allows any user to see and resolve conflicts. The Make Master option can be used to create and save a master dictionary - labeled_master.pkl - containing all labeled images (after reconciliation).

Import saved labels

The app saves a labeled_<username>.pkl file that contains a pickeled dictionary {image_name: label}. To import the dictionary, use the following sample code:

import pickle

with open("labeled_user1.pkl","rb") as f:
    label_dict = pickle.load(f)

Advanced usage


Once you are done labelling, use the flow_to_directory tool to copy images to distinct directories by label

flow_to_directory --input-directory data/labeled --output-directory data/sorted

Python object

The Tkinter app can also be started from a python environment

from simplabel import ImageClassifier
import tkinter as tk

root = tk.Tk() 
directory = "data/raw"
categories = ['dog', 'cat', 'bird']
MyApp = ImageClassifier(root, directory, categories)


This project is licensed under the GPLv3 License - see the file for details.


Testing of tkinter GUI is based on ivan_pozdeev's answer at Stackoverflow:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

simplabel-0.1.5.tar.gz (18.7 kB view hashes)

Uploaded source

Built Distribution

simplabel-0.1.5-py3-none-any.whl (29.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page