{"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":[{"wrong":"from perception import ImageHash","symbol":"metadata","correct":"from perception import metadata"}],"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,"search_vec":"'0.8.4':21 '3.10':24 '4.0':25 'cadenc':27 'comprehens':9 'develop':16 'dhash':40 'document':7 'everi':32 'flexibl':4 'hash':14,36,38 'imag':37 'irregular':29 'month':34 'percept':1,2 'perceptu':13,35 'phash':39 'product':18 'provid':3 'python':23 'releas':26 'research':15 'support':22 'test':10 'tool':11 'updat':31 'use':19 'version':20 'well':6 'well-docu':5 'whash':41","created_at":"2026-05-01T08:11:57.484339+00:00","updated_at":"2026-05-01T08:11:57.484339+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://pypi.org/project/perception/","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/perception/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-08-02","install_tag":null}}