Image Library 4.0
Image Library lets you manage images by associating tags to them.
- Tag images
- Search tagged images
- Replace/move image files while keeping all associated tags
- Manage tags (create, remove, associate type)
- Tag completion in queries and image tags editor
- Export query results as “playlists” (XML files)
- Apply pattern-based transformations to images paths
- Replace a tag by another on all concerned images at once
- List similar images (hash-based)
- Fully translated interface, available in English, French, and Esperanto
- Integrated SQL console
- Database auto-update
Image Library is not available on PyPI. Might be some day… I dunno… When I take the time to look into that.
Download the attached zip file in the release then unpack it where you want to install the app. Once unpacked, run the
setup.sh (Linux users) or
setup.bat (Windows users) file to install all required dependencies.
Version 3.1 and prior
You need to build the application in order to use it. To do so, run
build.py and wait for it to complete. Once it is
done, go into
build/ and copy the application directory (
Image-Library/) where you want to.
Delete all files and directories except database (
library.sqlite3, may differ if changed in config file) and
config.ini) files. Once done, follow installation instructions. Discard the new
file if you want to keep the previous configuration.
For versions 4.0+, database files are automatically updated. A backup of the old version will be created under the
<file name>-old_<old version>.sqlite3. For instance, updating the file
library.sqlite3 from version 3.1 will
create the backup file
Launch on Linux
./ImageLibrary.py. If it does not work, you might need to change file’s user
chmod u+x ./ImageLibrary.py.
Launch on Windows
Go through the File menu and click on Add Files to add images or Add Directory to import all images from a directory; or you can simply drag-and-drop files or directories into the main window.
You should see a dialog window with a preview of an image and a text field. This text field is where you have to type the tags for the displayed image. Once you’re satisfied, click on Apply & Continue or Finish to go to the next image. You can click on Skip to skip the current image and go directly to the next one.
While editing tags, you can choose where to move the current image by clicking on Move to…; the path is then displayed next to the button.
If the application found similar images already registered, a button labelled Similar Images… will appear above the text area. It will show a list of similar images, ordered by decreasing estimated similarity. You can select one of these images and copy its tags by clicking on Copy Tags (Warning: it will replace all tags in the text box).
Searching for registered images
You can search for images by typing queries in the search field. Syntax is as follow:
awill match images with tag
a bwill match images with both tags
a + bwill match images with tags
-awill match images without tag
ext:"png"will match images that are PNG files
name:"*awesome pic*"will match images whose name contains the string
awesome pic; the
*character matches any character, 0 or more times
path:"/home/user/images/summer?.png"will match images with paths like
/home/user/images/summers.png, etc.; the
?character matcher any character 0 or 1 times
similar_to:"/home/user/images/house.png"will match all images that are similar to
/home/user/images/house.png(if it is registered in the database)
Special tags accept two types of values: plain text, in between
" and regular expressions (regex) in between
As seen in the examples above, plain text values accept two special characters,
? that match respectively 0 or
more, and 0 or 1 characters. You can disable them by putting a
\ before (e.g.:
\* will match the character
literally). You also have to escape all single
\ by doubling them:
\\. For instance, to match all images whose path
C:\Users\me\images\, you will have to type
path:"C:\\Users\\me\\images\\*". If a path or file name
contains a double quote, you have to escape it in the same way:
Regular expressions follow Python’s format. See this page for
explanations of the syntax. Note that you have to escape all
/ too, as this is the delimiter.
More complex queries can be written by grouping with parentheses.
a (b + c) + -(d e) ext:"jp?g"
Here’s how to interpret it:
a (b + c)returns the set of images with both tags
band/or both tags
-(d + e) ext:"jp?g"=
-d -e ext:"jp?g"returns the set of JPG images without tags
e; note the
?to match both
The result is the union of both image sets.
The application also supports compound tags, i.e. tags defined from tag queries (e.g.: tag
animal could be defined as
cat + dog + bird). You cannot tag images directly with compound tags, they exist only for querying purposes.
External command line tool
An external SQLite command line interface is available to interact directly with the database. Use with extreme caution as you may break the database’s structure and render it unusable by the app.
./ImageLibrary_cmd.py. If you get errors, refer to Launch on Linux section.
The following configurations can be modified in the
config.ini file. If the file does not exist, launch the
application at least once to generate it.
File: path to database file; can be absolute or relative to the app’s root directory
falseto load or not thumbnails (can be changed from app)
ThumbnailSize: thumbnail size in pixels (can be changed from app)
ThumbnailLoadThreshold: maximum number of thumbnails that can be displayed without warning when querying images
Language: language code of app’s interface; can be either
frfor French, or
Found a bug?
If you encounter a bug or the app crashed, check the error log located in
logs/error.log and see if there’s an error.
You can send me a message or open an issue with the error and a description of how you got this error, that would be
- Python 3.8 or above (Will not work with older versions)
- PyQt5 (GUI)
- Lark (Query parsing)
- SymPy (Query simplification)
- scikit-image (Image comparison)
- OpenCV2 (Image comparison)
- Pyperclip (Copy text to clipboard)
See requirements.txt for up-to-date list.
- Damien Vergnet @Darmo117
Compound tags: define tags based on tag queries
Fully translated interface: English, French, and Esperanto
GIFs are now animated
Compare images (based on difference hashing)
Move several files at once
Execute pattern-based replacements on image paths
Replace a tag by another on all concerned images at once
Integrated SQL console
Tags suggestion in query field and image editing dialog
Directories can now be dragged and dropped
Special tags now support regexes
New special tag
path: queries all images whose path matches the value
New special tag
similar_to: queries all images that are similar to the specified one
New special tag joker
?in plain text mode: matches 0 or 1 character
Resizable image preview in image editing dialog
Query images without any tags
Export selected images as a XML playlist
Sortable tables in tags editing dialog
Using system icon theme on compatible Linux distributions
Change database file from within the application
Context menus in tags tree and image lists
Special tag values now require double quotes
"for plain text mode (only available mode in previous versions)
No need to escape spaces anymore
Single error message when several image could not be deleted instead of individual ones
Directories are now loaded recursively
Bugfix: Tag search no longer triggers twice when pressing Enter
Added support of UTF-8 letters to image queries
Added 'name' metatag to filter images by file name (without extension)
Metatag values now support the wildcard character '*'. For example name:image* will return images having their name starting with 'image'
Added missing license
Images without type metadata would not load
Files could not be moved between disks on Windows
Added a tree listing all currently defined tags (sorted by type)
Types can now have colors
Images can be filtered by file type using
Added error logs (can be found in
Add images and associate tags to it
Remove/replace added images
Modify/remove tags to added images
Associate types to tags