czk
A CLI wrapper around czkawka_cli focused on usability and easier analysis of duplicate images and videos.
Features
- Dry-run and live deletion modes with colorized, grouped terminal output
- CSV and JSON reports per run
- Interactive SQL analysis via DuckDB
- Self-contained HTML visual report with inline image/video previews, search, and pagination
Requirements
- macOS or Linux
czkawka_cli— duplicate detection engineduckdbCLI — required forczk analyze- Python +
uv
Installation
# From PyPI (recommended)
uv tool install czk-tool
# or with pip
pip install czk-tool
# From source
uv tool install --editable .
Usage
czk test <directory> # Dry run — scan for duplicates, no deletion
czk execute <directory> # Move duplicates to the OS trash (keep biggest; newest on size tie)
czk analyze <directory> # Interactive DuckDB SQL session over scan results
czk viz <directory> # Generate a self-contained HTML visual report
czk check is an alias for czk test; czk analyse is an alias for czk analyze.
Options
| Flag | Description |
|---|---|
--media {both,images,videos} |
Media type to scan (default: both) |
-s, --similarity-preset |
Image similarity preset: Original, VeryHigh, High, Medium, Small, VerySmall, Minimal (default: High) |
-c, --hash-size {8,16,32,64} |
Perceptual hash size for images (default: 32) |
-g, --hash-alg |
Hash algorithm for images: Mean, Gradient, Blockhash, VertGradient, DoubleGradient, Median (default: Gradient) |
-z, --image-filter |
Resize filter for images: Lanczos3, Nearest, Triangle, Faussian, Catmullrom (default: Nearest) |
-t, --tolerance 0..20 |
Similarity tolerance for videos (default: 10) |
--top N |
Limit duplicate groups in previews (default: 50) |
--all |
Show all duplicate groups, overrides --top |
--out-dir <path> |
Output directory (default: <system-temp>/czk-reports) |
--no-color |
Disable colored output |
Output
Each run writes timestamped artifacts to the output directory:
<base>-<media>-<YYYYMMDD-HHMMSS>.json<base>-<media>-<YYYYMMDD-HHMMSS>.csv<base>-viz-<YYYYMMDD-HHMMSS>.html(czk vizonly)
CSV columns: index, file_to_keep, files_to_remove, count
Keep rule
czkawka_cli only scans; czk decides which file to keep and does the deletion itself, so the CSV always matches what execute deletes. In each group it keeps the biggest file. If sizes tie, it keeps the most recently modified one, then falls back to the lexicographically first path (ascending Unicode code point order, e.g. messages/ before timeline/).
execute moves removed files to the OS trash (macOS Trash, Windows Recycle Bin, freedesktop.org trash on Linux) via Send2Trash, so they can be restored.
Disclaimer
Parts of this project were assisted by AI tooling. Review all commands carefully before running, especially deletion workflows. This software is provided "as is" without warranties of any kind. The authors are not liable for any data loss or other damages resulting from use.
1 maintainer
Metadata
1 maintainer
Release files for czk-tool 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| czk_tool-2.0.0.tar.gz | 37.9 kB | Without provenance | Details for czk_tool-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| czk_tool-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for czk_tool-2.0.0-py3-none-any.whl |
Total release size: 69.0 kB
Release files / czk_tool-2.0.0.tar.gz
| Download URL | czk_tool-2.0.0.tar.gz |
|---|---|
| Size | 37.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7deba34791cd54b450fde5034c0a1eb7ab78bb31fc1b40f3968502ad3edfdd22
|
|
BLAKE2b-256 checksum How to use checksums |
f9f7a5e1f15ae511eb5515cea7bdccd8e8985825e28ad991e3d72be407d3014d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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 / czk_tool-2.0.0-py3-none-any.whl
| Download URL | czk_tool-2.0.0-py3-none-any.whl |
|---|---|
| Size | 31.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1e17b43e3780dda0c3e9a39880bcbf174a5981ee901b5c5cea14cbb1a9e984df
|
|
BLAKE2b-256 checksum How to use checksums |
6c46c9464a485415e1270d125e87c2fafd4efa3dfdfdf8af4bcee51034861f17
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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}
|
Security for czk-tool 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
