{"id":24228,"library":"perception","title":"Perception","description":"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.","status":"active","version":"0.8.4","language":"python","source_language":"en","source_url":"https://github.com/thornycrackers/perception","tags":["perceptual hashing","image hashing","phash","dhash","whash"],"install":[{"cmd":"pip install perception","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Image loading and processing","package":"Pillow","optional":false},{"reason":"Numerical operations on hashes","package":"numpy","optional":false},{"reason":"Signal processing for some hashes","package":"scipy","optional":true}],"imports":[{"note":"Old import path deprecated in v0.7; ImageHash is now a top-level alias.","wrong":"from perception.hashers import ImageHash","symbol":"ImageHash","correct":"from perception import ImageHash"},{"note":"Submodule must be imported explicitly; direct attribute access fails.","wrong":"import perception.hashers","symbol":"hashers","correct":"from perception import hashers"},{"note":"","wrong":"","symbol":"tools","correct":"from perception import tools"}],"quickstart":{"code":"from perception import hashers\n\nhasher = hashers.PHash()\nhash1 = hasher.compute('image1.jpg')\nhash2 = hasher.compute('image2.jpg')\ndistance = hash1 - hash2\nprint(f'Hamming distance: {distance}')\n","lang":"python","description":"Compute perceptual hashes for two images and compare using Hamming distance."},"warnings":[{"fix":"Use 'from perception import ImageHash' instead.","message":"In v0.7, ImageHash became a top-level export. Importing from 'perception.hashers.ImageHash' now raises ImportError.","severity":"breaking","affected_versions":">=0.7"},{"fix":"Instantiate 'hashers.DHash()' instead of calling 'hashers.dhash()'.","message":"The 'perception.hashers.dhash' function is deprecated in favor of 'perception.hashers.DHash' class.","severity":"deprecated","affected_versions":">=0.8"},{"fix":"Check file existence before computing, or catch FileNotFoundError if using from perception.tools.","message":"Computing a hash with a non-existent image file returns a zero hash without raising an error. This may silently produce false matches.","severity":"gotcha","affected_versions":"all"},{"fix":"Use hash1 - hash2 for distance; for comparison, convert to binary string manually.","message":"The __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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'from perception import hashers' before using hashers.","cause":"Hashers submodule not imported; perception package exposes only ImageHash and tools by default.","error":"AttributeError: module 'perception' has no attribute 'hashers'"},{"fix":"Use 'from perception import ImageHash'.","cause":"ImageHash moved to top level in v0.7.","error":"ImportError: cannot import name 'ImageHash' from 'perception.hashers'"},{"fix":"Ensure both operands are ImageHash instances: 'hash1 - hash2'.","cause":"Subtracting an int from an ImageHash is not supported; only ImageHash - ImageHash works.","error":"TypeError: unsupported operand type(s) for -: 'ImageHash' and 'int'"},{"fix":"Compare explicitly: 'if hash1.distance(hash2) == 0:' or 'if hash1 == hash2:'.","cause":"ImageHash does not implement __bool__; cannot be used in if condition directly.","error":"ValueError: The truth value of an ImageHash is ambiguous"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}