๐Ÿงฟ Pupyl is a really fast image search library which you can index your own (millions of) images and find similar images in millisecond.

approximate-nearest-neighbors, convolutional-neural-networks, gif-search, image-search, pythonic-library
pip install pupyl==0.14.6


pupyl pupyl-ci codecov anaconda PyPI version Documentation Status Downloads CII Best Practices Anaconda-Server Badge

pupyl - A Python Image Search Library


Table of contents

๐Ÿงฟ pupyl what?

The pupyl project (pronounced pyooยทpiel) is a pythonic library to perform image search tasks (even over animated GIFs). It's intended to make easy reading, indexing, retrieving and maintaining a complete reverse image search engine. You can use it in your own data pipelines, web projects and wherever you find fit!

๐ŸŽ‰ Getting started

๐Ÿ“ฆ Installation

Installing pupyl on your environment is pretty easy:

# pypi
pip install pupyl


# anaconda
conda install -c policratus pupyl

For installation troubleshooting, visit troubleshooting.

๐Ÿšธ Usage

You can call pupyl's objects directly from your application code. For this example, a sample database will be indexed and after that, the following image will be used as a query image (credits: @dlanor_s):


pupyl also supports using animated gifs as query images and can store and retrieve it too.

from pupyl.search import PupylImageSearch
from pupyl.web import interface

SEARCH = PupylImageSearch()


# Using, for instance, a remote image. Local images have pretty faster results.
QUERY_IMAGE = 'https://images.unsplash.com/photo-1520763185298-1b434c919102?w=224&q=70'


Disclaimer: the example above creates pupyl assets on your temporary directory. To define a non-volatile database, you should define data_dir parameter.

This will return:

# Here's the simplest possible result
> [486, 12, 203, 176]

With more information and returning image metadata from the results:

# The results with image metadata
[*SEARCH.search(QUERY_IMAGE, return_metadata=True)]

Now an excerpt of the (possible) return is:

        "id": 486,
        "internal_path": "/tmp/pupyl/0/486.gif",
        "original_access_time": "2021-12-03T13:23:47",
        "original_file_name": "icegif-5690.gif",
        "original_file_size": "261K",
        "original_path": "/tmp/tmp3gdxlwr6"
        "id": 12,
        "internal_path": "/tmp/pupyl/0/12.gif",
        "original_access_time": "2021-12-03T13:23:46",
        "original_file_name": "roses.gif",
        "original_file_size": "1597K",
        "original_path": "/tmp/tmp3gdxlwr6"

To interact visually, use the web interface:

# Opening the web interface

A glimpse of the web interface, visualizing the results shown above:


Alternatively, you can interact with pupyl via command line. The same example above in CLI terms:

๐Ÿš Command line interface

# Indexing images
pupyl --data_dir /path/to/your/data/dir index /path/to/images/

# Opening web interface
pupyl --data_dir /path/to/your/data/dir serve

# Searching using command line interface
pupyl --data_dir /path/to/your/data/dir search /path/to/query/image.ext

๐Ÿ’ก Type pupyl --help to discover all the CLI's capabilities.

๐Ÿ“Œ Dependencies

See all dependencies here: dependencies.

๐Ÿ“ Documentation

See a getting started guide and the API reference on https://pupyl.readthedocs.io/.

๐Ÿ–Š๏ธ Citation

If you use pupyl in your publications or projects, please cite:

    author = {Nelson Forte de Souza Junior},
    title = {pupyl - A Python Image Search Library},
    howpublished = {\url{https://github.com/policratus/pupyl}},
    year = {2021}