perception

library0.9.1pypypi✓ verified 79d ago

Perception provides flexible, well-documented, and comprehensively tested tooling for perceptual hashing research, development, and production use. Version 0.8.4 supports Python >=3.10 <4.0. Release cadence is irregular, with updates every few months.

ai-ml data serialization

pip install perception

package ↗homepage ↗

INSTALL

IMPORT

SIG · PERCEPTION

perception

ai-mlpythonv0.9.1

Install

12.1s avg

Import

—

Disk

407MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 12.3s

py 3.11

✕ build_error

✓ 12.6s

py 3.12

✕ build_error

✓ 12s

py 3.13

✕ build_error

✓ 11.5s

py 3.9

✓ —

✕ build_error

407MB installed

● package 407MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

metadata

✓ from perception import metadata

✗ from perception import ImageHash

Compute perceptual hashes for two images and compare using Hamming distance.

from perception import hashers hasher = hashers.PHash() hash1 = hasher.compute('image1.jpg') hash2 = hasher.compute('image2.jpg') distance = hash1 - hash2 print(f'Hamming distance: {distance}')

Debug

Known issues

breakingIn v0.7, ImageHash became a top-level export. Importing from 'perception.hashers.ImageHash' now raises ImportError.

fix

Use 'from perception import ImageHash' instead.

affects: >=0.7

deprecatedThe 'perception.hashers.dhash' function is deprecated in favor of 'perception.hashers.DHash' class.

fix

Instantiate 'hashers.DHash()' instead of calling 'hashers.dhash()'.

affects: >=0.8

gotchaComputing a hash with a non-existent image file returns a zero hash without raising an error. This may silently produce false matches.

fix

Check file existence before computing, or catch FileNotFoundError if using from perception.tools.

affects: all

gotchaThe __sub__ method of ImageHash returns an integer Hamming distance, but the hash objects themselves are not directly comparable with <, >, etc. Only equality and subtraction work.

fix

Use hash1 - hash2 for distance; for comparison, convert to binary string manually.

affects: all

Upgrade

Version history

0.9.1latest on PyPI · released May 26, 2026

Audit

Dependencies

PillowrequiredImage loading and processing

numpyrequiredNumerical operations on hashes

scipyoptionalSignal processing for some hashes

Agent activity

6 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/perception/ ↗

homepagehttps://pypi.org/project/perception/ ↗