Upgrading from 1.x

image-match 2.0 is a modernization of the original project. The guiding rule was data compatibility: signatures, word encodings, and stored record formats are unchanged, so an index built with 1.x keeps working — no reindex is needed to keep searching existing data.

What stays compatible

  • Signatures — ImageSignature still produces the same 648-dimensional int8 vector (n_grid=9, crop_percentile=(5, 95), P=34). A signature generated by 1.x matches the same images under 2.0.

  • Record format — simple_word_0 … simple_word_62 plus path, signature, timestamp, and metadata are stored exactly as before.

  • Search semantics — word-overlap pre-filter, normalized_distance scoring, and the distance_cutoff=0.45 default are unchanged.

  • Public API names — SignatureES, SignatureMongo, add_image, search_image, make_record, get_words, words_to_int are all still where they were.

Breaking changes

Python version

Requires Python 3.13 or newer (1.x targeted Python 2.7/early 3.x).

Backend dependencies are extras

elasticsearch, opensearch-py, and pymongo are no longer installed by default. Install the extra for your backend:

pip install "image-match[elasticsearch]"   # or [opensearch], [mongo],
                                           # [elasticsearch-async], …
SignatureES constructor

  • doc_type was removed — Elasticsearch 7 no longer uses mapping types. Indexes created with a doc_type still work; new documents are simply indexed without one.

  • timeout is now a string ("10s", default) rather than an int of seconds.

  • Argument order is now (es, index, timeout, size, …). If you called the 1.x signature positionally — SignatureES(es, 'images', 'image', 10, 100) — switch to keyword arguments.

Elasticsearch client

Requires elasticsearch 7.x (>=7.17,<8). The 8.x/9.x clients removed the body= parameter the driver uses; OpenSearch users should install the [opensearch] extra instead.

MongoDB driver

Requires pymongo>=4.0. SignatureMongo(collection) itself is unchanged.

New in 2.0

  • OpenSearch drivers (SignatureOpenSearch, SignatureOpenSearchKNN) for OpenSearch 2.x and 3.x, including a knn_vector/HNSW index — see Migrating to the OpenSearch k-NN index for moving an existing index to k-NN.

  • Async drivers for Elasticsearch and OpenSearch.

  • add_images() bulk ingestion and insert_records() for pre-generated records; delete_image() removes all records with an exact path.

  • pre_filter metadata filtering on search_image, refresh_after on inserts, minimum_should_match/use_filter_context tuning, and a configurable delete_duplicates_limit.