perception 
perception provides flexible, well-documented, and comprehensively tested tooling for perceptual hashing research, development, and production use. See the documentation for details.
Background
perception was initially developed at Thorn as part of our work to eliminate child sexual abuse material from the internet. For more information on the issue, check out our CEO's TED talk.
Getting Started
Installation
pip install perception
Optional extras
perception provides optional extras for additional functionality:
approximate-deduplication– FAISS-based approximate-nearest-neighbor deduplication and graph community/clique detection (used byperception.approximate_deduplicationandperception.local_descriptor_deduplication)benchmarking– tools for benchmarking perceptual hashesmatching– async matching utilitiespdq– Facebook's PDQ hash support
Note for benchmarking extra users: The benchmarking extra depends on
albumentations, which in turn requires opencv-python-headless. However,
perception already depends on opencv-contrib-python-headless (needed for
contrib modules such as cv2.img_hash and cv2.SIFT_create). Installing both
OpenCV distributions simultaneously causes file-level conflicts.
If you are using uv, this is handled automatically:
uv pip install "perception[benchmarking]"
If you are using plain pip, install the extra and then force-reinstall the
contrib variant to remove the conflicting headless package:
pip install "perception[benchmarking]"
pip install --force-reinstall --no-deps opencv-contrib-python-headless
Hashing
Hashing with different functions is simple with perception.
from perception import hashers
file1, file2 = 'test1.jpg', 'test2.jpg'
hasher = hashers.PHash()
hash1, hash2 = hasher.compute(file1), hasher.compute(file2)
distance = hasher.compute_distance(hash1, hash2)
Examples
See below for end-to-end examples for common use cases for perceptual hashes.
Supported Hashing Algorithms
perception currently ships with:
- pHash (DCT hash) (
perception.hashers.PHash) - Facebook's PDQ Hash (
perception.hashers.PDQ) - dHash (difference hash) (
perception.hashers.DHash) - aHash (average hash) (
perception.hashers.AverageHash) - Marr-Hildreth (
perception.hashers.MarrHildreth) - Color Moment (
perception.hashers.ColorMoment) - Block Mean (
perception.hashers.BlockMean) - wHash (wavelet hash) (
perception.hashers.WaveletHash)
Contributing
To work on the project, start by doing the following.
# Install local dependencies for code completion,
# testing, and linting.
make init
To do a (close to) comprehensive check before committing code, use make precommit.
To implement new features, please first file an issue proposing your change for discussion.
To report problems, please file an issue with sample code, expected results, actual results, and a complete traceback.
Alternatives
There are other packages worth checking out to see if they meet your needs for perceptual hashing. Here are some examples.
2 maintainers
Metadata
2 maintainers
Release files for Perception 0.9.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| perception-0.9.2.tar.gz | 11.0 MB | Details |
Built distributions (wheels)
Total release size: 122.6 MB
Release files / perception-0.9.2.tar.gz
| Download URL | perception-0.9.2.tar.gz |
|---|---|
| Size | 11.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bb49aea6baeaf90f3eddd85e8c039eb83cf6c7d486a11adb8eadfdb72d73675f
|
|
BLAKE2b-256 checksum How to use checksums |
85cbdfda9ced5ccabec374f440804ee4d3b0fe1fc1e47604807b3af6861baf77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp313-cp313-win_amd64.whl
| Download URL | perception-0.9.2-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 6.7 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d6ab1e648eafca29e346533b05454936ef5cd4ce219a335f6456726ea9739f2b
|
|
BLAKE2b-256 checksum How to use checksums |
e0b48461d5d19a0598fb0c9c85e14f5020fe402a5218f6c6c1be821a2cc5a454
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp313-cp313-manylinux_2_24_x86_64.whl
| Download URL | perception-0.9.2-cp313-cp313-manylinux_2_24_x86_64.whl |
|---|---|
| Size | 7.4 MB |
| Tags | CPython 3.13 Linux glibc 2.24+ x86-64 |
|
SHA-256 checksum How to use checksums |
c39146dbe950db9bfc07c9186ab0cc0d659b38692739868e87cfabc9ea1db885
|
|
BLAKE2b-256 checksum How to use checksums |
7044debcfeabcc22afbe1aa38d2b3fe64dbe889c5aa4e907fafce47fde486b08
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp313-cp313-manylinux_2_24_aarch64.whl
| Download URL | perception-0.9.2-cp313-cp313-manylinux_2_24_aarch64.whl |
|---|---|
| Size | 7.3 MB |
| Tags | CPython 3.13 Linux glibc 2.24+ ARM64 |
|
SHA-256 checksum How to use checksums |
d8b9664ec0154f01d938dd32f5bbc54f4ffc44b2cec8d5214a18701cb901ac10
|
|
BLAKE2b-256 checksum How to use checksums |
661e3fe64341ebe4535e901612b537a1e3e057c37f35de7c52de35ae940555c7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp313-cp313-macosx_26_0_arm64.whl
| Download URL | perception-0.9.2-cp313-cp313-macosx_26_0_arm64.whl |
|---|---|
| Size | 6.5 MB |
| Tags | CPython 3.13 macOS 26.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
eab775f988e84e5e24878386f19ae7c157b35d9f0183d8de51ed549637ef3d51
|
|
BLAKE2b-256 checksum How to use checksums |
5d67db9e324e30fe4e99ada44b70984d95d88c4133fe8c548f4a0b613677bdd8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp312-cp312-win_amd64.whl
| Download URL | perception-0.9.2-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 6.7 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
20c64d309492cbfb0e8f652ad74a3ba10a60046088273425396eb3bb1ae60ff4
|
|
BLAKE2b-256 checksum How to use checksums |
f579b72d8854f8bb678f5494d96986f9ba9f6cae50085a2a650141ccc8086291
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp312-cp312-manylinux_2_24_x86_64.whl
| Download URL | perception-0.9.2-cp312-cp312-manylinux_2_24_x86_64.whl |
|---|---|
| Size | 7.2 MB |
| Tags | CPython 3.12 Linux glibc 2.24+ x86-64 |
|
SHA-256 checksum How to use checksums |
0c7d70a794dcdd99312b614a0b847f91a724fcf18e49bf8e3b9fe7b9c818df93
|
|
BLAKE2b-256 checksum How to use checksums |
5a17c61782e5d5b22f086ff9b1b8c34006a62f036b3b4e59d3b56b91ac956fa4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp312-cp312-manylinux_2_24_aarch64.whl
| Download URL | perception-0.9.2-cp312-cp312-manylinux_2_24_aarch64.whl |
|---|---|
| Size | 7.2 MB |
| Tags | CPython 3.12 Linux glibc 2.24+ ARM64 |
|
SHA-256 checksum How to use checksums |
1ebc15faaf26f836b02cb2985398d233761af8f21b9981545337ad19cd2fe3bd
|
|
BLAKE2b-256 checksum How to use checksums |
4b3800b0febdec84c2419248754a5250b4359fa584aa5e0c4006119b231c4db7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp312-cp312-macosx_10_13_universal2.whl
| Download URL | perception-0.9.2-cp312-cp312-macosx_10_13_universal2.whl |
|---|---|
| Size | 6.7 MB |
| Tags | CPython 3.12 macOS 10.13+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
9e3024f57e2ee1691a6b0a28ab9cefa06ba931a62e0173311b2e2f3bafee4076
|
|
BLAKE2b-256 checksum How to use checksums |
bc48d5e094c8a1163d0287d3f0c3188df7de6e0814188d686a02849d9411d540
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp311-cp311-win_amd64.whl
| Download URL | perception-0.9.2-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 6.7 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
6f67b3762cdba679e281c3562f0682e926ec8ff1683f8b4d865018347390b2ba
|
|
BLAKE2b-256 checksum How to use checksums |
906b36596ce62575e9995ae91a6038475bafbf051bde6dc9426ff3d0e68160da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp311-cp311-manylinux_2_24_x86_64.whl
| Download URL | perception-0.9.2-cp311-cp311-manylinux_2_24_x86_64.whl |
|---|---|
| Size | 7.4 MB |
| Tags | CPython 3.11 Linux glibc 2.24+ x86-64 |
|
SHA-256 checksum How to use checksums |
33fe8f3658d2e433c4ec96e012c95ae8fa59b45887262f6fdd20958f78ad339c
|
|
BLAKE2b-256 checksum How to use checksums |
3ea36382ccc55776a1e096843c7e5573cb149888ec11304ce2c5e805e26f6428
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp311-cp311-manylinux_2_24_aarch64.whl
| Download URL | perception-0.9.2-cp311-cp311-manylinux_2_24_aarch64.whl |
|---|---|
| Size | 7.4 MB |
| Tags | CPython 3.11 Linux glibc 2.24+ ARM64 |
|
SHA-256 checksum How to use checksums |
8d2e0cfa79f40f7c68e8231bd5b00e3778ab0506357363c98c129e34374fc8f8
|
|
BLAKE2b-256 checksum How to use checksums |
37a75d14186757a9f48294fcfa19d197605a68f3e48a1554978a7519c5aa0742
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp311-cp311-macosx_10_9_universal2.whl
| Download URL | perception-0.9.2-cp311-cp311-macosx_10_9_universal2.whl |
|---|---|
| Size | 6.6 MB |
| Tags | CPython 3.11 macOS 10.9+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
5126678f5dfaef22b671dde12aa05b7e769d41aefc32204f6aa1486e91a604eb
|
|
BLAKE2b-256 checksum How to use checksums |
86e737cb9959384855437367d9b44ffd7484e900f09de26e9a24343ba8cadc49
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp310-cp310-win_amd64.whl
| Download URL | perception-0.9.2-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 6.7 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
281739022651f52ed5a1ddaaad06b5597ff5307610d4b507cd6bceaedd9df812
|
|
BLAKE2b-256 checksum How to use checksums |
643a66828133caa594aee144257f2cc216a610bcbf66fdbbf0fdcafd4a38f86c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp310-cp310-manylinux_2_24_x86_64.whl
| Download URL | perception-0.9.2-cp310-cp310-manylinux_2_24_x86_64.whl |
|---|---|
| Size | 7.4 MB |
| Tags | CPython 3.10 Linux glibc 2.24+ x86-64 |
|
SHA-256 checksum How to use checksums |
935267cdaa747ae2051796fe793977e91322d50ebe4605aca650637cb5a38905
|
|
BLAKE2b-256 checksum How to use checksums |
101ad093b9d128f1c20c2d05a552ab131e92e6fc885a9e13d8e214646f35282d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp310-cp310-manylinux_2_24_aarch64.whl
| Download URL | perception-0.9.2-cp310-cp310-manylinux_2_24_aarch64.whl |
|---|---|
| Size | 7.3 MB |
| Tags | CPython 3.10 Linux glibc 2.24+ ARM64 |
|
SHA-256 checksum How to use checksums |
6eb7bb116000cb1b232f19aeec187328c68b5e40460f354105c3caff736facb3
|
|
BLAKE2b-256 checksum How to use checksums |
b632b2b0a3cedb505a750521281056e632468b6ba923df64290a92f32f034d5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / perception-0.9.2-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | perception-0.9.2-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 6.5 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4d5fc694ed92171d9359ed6caca3e3e674bf60e8098ee5b992755387209003f7
|
|
BLAKE2b-256 checksum How to use checksums |
edb5dfc2a5c65604ac91b637445f5281adc0d17589e42e71b7ec5d2c0ff224d5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
