instructions/Instruction.md
Czkawka contains three independent frontends - the terminal app (CLI) and two graphical apps (Krokiet and GTK) which share the core module.
Krokiet is the new primary GUI written in Slint, providing a consistent cross-platform experience with better performance and fewer bugs.
GTK is the older GUI that is still maintained but will eventually be replaced by Krokiet.
Krokiet is the new Czkawka frontend written in Slint. It provides a modern, consistent interface across all platforms (Linux, Windows, macOS) and is designed to be more performant and stable than the GTK version.
The Krokiet interface consists of several key areas:
Accessible via the settings button, contains multiple subsections:
General Settings
Performance Settings
Tool-Specific Settings Each tool has its own settings page with advanced options:
Krokiet have full support for multiple languages in GUI. Language can be changed in Settings → General → Language.
Note: GTK GUI is the older interface that is still maintained but will eventually be replaced by Krokiet. For new users, we recommend using Krokiet.
The GUI is built from different pieces:
This short glossary contains terms used consistently by all frontends (CLI, GTK and Krokiet).
Reference paths
Included / Excluded paths
Configuration vs Cache
GTK GUI is fully translatable.
For now at least 10 languages are supported(some was translated by automatic translation, so may not be perfect).
It is possible to open selected files by double-clicking on them.
To open multiple file just select desired files with CTRL key pressed and still when clicking this key, double-click at selected items with left mouse button.
To open folder containing selected file, just click twice on it with right mouse button.
To invert a selection of files, click on a file with the middle mouse button, and it will invert the selection of the other files in the same group.
By default, current path is loaded to included directory and excluded directories are filled with default paths.
It is possible to override this, by adding arguments when opening app e.g. czkawka_gui /home /usr --/home/rafal --/home/zaba which means that /home and /usr directories will be checked and /home/rafal and /home/zaba will be excluded.
When using additional command line arguments, saving at exit option become disabled, so this current info about directories will not be saved until user save it manually.
Both relative and absolute path are supported, so user can use both ../home and /home.
After adding a path it is possible to mark one or more paths as a Reference path. Reference paths (files or folders) cannot be acted upon, e.g. selected, moved or removed. This behaviour can be useful if you want to leave a path untouched, but still use it for comparison against others.
Czkawka CLI frontend is great to automate some tasks like removing empty directories.
To get general info how to use it just try to open czkawka_cli in console czkawka_cli
You should see a lot of examples how to use this app.
If you want to get more detailed info about certain tool, just add after its name -h or --help to get more details.
By default, all tools only write about results to console, but it is possible with specific arguments to delete some files/arguments or save it to file.
App returns exit code 0 when everything is ok, 1 when some error occurred and 11 when some files were found.
This section describes typical workflows for common tasks using Czkawka.
Scenario: You want to find and remove duplicate files from your Downloads folder, but keep files from your Documents folder as reference.
Steps (Krokiet):
Steps (GTK):
Scenario: You have multiple folders with photos and want to find similar images (different sizes, minor edits).
Steps (Krokiet):
Scenario: Disk space is running low, you want to find the largest files.
Steps:
Scenario: You want to compare your working files against a master/backup collection without risking deletion of the master files.
Use Cases:
How to Use:
Configuration files (frontend-specific)
czkawka_gui_config.txt — GTK GUI configuration stored under the user config directoryCache files (shared across frontends)
cache_similar_image_SIZE_HASH_FILTER.bin/json — image hashes and cachecache_broken_files.txtcache_duplicates_HASH.txt — duplicates cache (only fully hashed files bigger than configured threshold are stored)cache_similar_videos.bin/jsonIt is possible to modify files with JSON extension (may be helpful when moving files to different disk or trying to use cache file on different computer). To do this, it is required to enable in settings option to generate also cache json file. By default, cache files with bin extension are loaded, but if it is missing (can be renamed or removed), then data from json file is loaded if exists.
Config files are located in this path:
Linux - /home/username/.config/czkawka
Linux Flatpak - /home/username/.var/app/com.github.qarmin.czkawka/config/czkawka
Mac - /Users/username/Library/Application Support/pl.Qarmin.Czkawka
Windows - C:\Users\Username\AppData\Roaming\Qarmin\Czkawka\config
Cache should be here:
Linux - /home/username/.cache/czkawka
Linux Flatpak - /home/username/.var/app/com.github.qarmin.czkawka/cache/czkawka
Mac - /Users/Username/Library/Caches/pl.Qarmin.Czkawka
Windows - C:\Users\Username\AppData\Local\Qarmin\Czkawka\cache
it is possible to change cache/config location by using CZKAWKA_CONFIG_PATH and CZKAWKA_CACHE_PATH env
e.g.
CZKAWKA_CONFIG_PATH="/media/rafal/Ventoy/config" CZKAWKA_CACHE_PATH="/media/rafal/Ventoy/cache" krokiet
It is possible to create portable version of app, by using running czkawka/krokiet with such script from pendrive:
open_czkawka.sh - on pendrive(along with czkawka/krokiet binary)
#!/bin/bash
CZKAWKA_CONFIG_PATH="$(dirname "$(realpath "$0")")/config"
CZKAWKA_CACHE_PATH="$(dirname "$(realpath "$0")")/cache"
./czkawka_gui
Cargo.toml file, this lines(small performance boost, big decrease in binary size):[profile.release]
lto = "thin" # or "fat"
RUSTFLAGS="-C target-cpu=native" cargo build --release
or adding it globally to ~/.cargo/config.toml
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = [
"-C", "target-cpu=native",
]
czkawka_gui_config.txt and add/remove/change directories as you want.cache_similar_image(to be able to use it again) or delete it - cache will then regenerate but with smaller number of entries and this way it should load and save cache faster.Use prehash cache which enables caching such things.Delete outdated cache entries automatically which automatically clear this, but this can be disabled.Remove outdated results will do it manually.Duplicate Finder allows you to search for files and group them according to a predefined criterion:
By name - Compares and groups files by name e.g. /home/john/cats.txt will be treated like a duplicate of a file named
/home/lucy/cats.txt. This is the fastest method, but it is very unreliable and should not be used unless you know
what you are doing.
By size - Compares and groups files by their size (in bytes and perfect matches only). It is as fast as the previous mode and usually gives better results with duplicates, but I also do not recommend using it if you do not know what you are doing.
By size and name - A mode that first compares files by size and then by name. Just like checking by size and name, this mode is not reliable.
By hash - A mode containing a check of the hash (cryptographic hash) of a given file which determines with great probability whether the files are identical.
This is the slowest, but almost 100% sure way to compare the files for being the same.
Because the hash is only checked inside groups of files of the same size, it is practically impossible for two different files to be considered identical.
It consists of 3 steps:
Grouping files of identical size - allows you to throw away files of unique size, which are already known to have no duplicates at this stage.
PreHash check - Each group of files of identical size is placed in a queue using all processor threads (each action in the group is independent of the others). In each such group a small fragment of each file (2KB) is loaded in turn and then hashed. All files whose partial hashes are unique within the group are removed from it. Using this step usually allows me to reduce the time of searching for duplicates almost by half.
Checking the hash - After leaving files that have the same beginning in groups, you should now check the whole contents of the file to make sure they are identical.
This tool finds files with zero bytes size.
Process
This is a fast operation since it only requires reading file metadata without accessing file contents.
This tool finds directories that contain no files or subdirectories.
Process
Example
Consider four directories: /cow/, /cow/ear/, /cow/ear/stack/, /cow/ear/flag/
If /cow/ear/flag/ contains a file:
/cow/ear/flag/ is marked as not empty/cow/ear/ and /cow/ are marked as not empty/cow/ear/stack/ may still be emptyThis tool finds the largest or smallest files in the specified directories.
Process
Useful for finding large files that take up disk space or identifying unusually small files that may be incomplete downloads.
This tool finds temporary files based on a predefined list of common temporary file extensions and names.
Detected patterns Files with the following extensions or names are considered temporary:
["#", "thumbs.db", ".bak", "~", ".tmp", ".temp", ".ds_store", ".crdownload", ".part", ".cache", ".dmp", ".download", ".partial"]
This list covers the most common temporary files created by operating systems and applications. For more comprehensive system cleanup, consider using specialized tools like BleachBit.
This tool finds broken symbolic links.
Process
Both error types are reported in the results.
This tool finds duplicate or similar music files by comparing metadata tags or audio content.
Process
mp3, flac, m4aartist, title, year, bitrate, genre, lengthDuplicate Tags Mode
bataty (feat. romba) → bataty)Similar Content Mode
Results show groups of files with matching tags or similar audio content.
A tool for detecting similar images that may differ in aspects such as watermarks, size, or compression artifacts.
Currently, it works well for images that have not been rotated.
Image is resized to 8x8, 16x16, 32x32, or 64x64 pixels (inside image_hasher crate)
A perceptual hash is computed for each image that is not already present in the cache
Unlike cryptographic hashes, which produce completely different outputs for slight variations:
11110 ==> AAAAAB
11111 ==> FWNTLW
01110 ==> TWMQLA
Perceptual hashes generate similar outputs for similar images:
11110 ==> AAAAAB
11111 ==> AABABB
01110 ==> AAAACB
Users can select from five different hash types:
GradientMeanVertGradientBlockhashDoubleGradientBefore hashing, images are typically resized to simplify computations. Supported resizing algorithms:
Lanczos3GaussianCatmullRomTriangleNearestSupported hash sizes: 8x8, 16x16, 32x32, 64x64
Both the resizing method and hash size can be adjusted within the application.
Each configuration generates separate cache files to prevent invalid results across different settings.
0 or 255. These images are silently excluded from the final results but remain stored in the cache.test.jpg file in a folder and run czkawka_cli tester -iThe faster comparison option ensures that each pair of results is compared only once, significantly improving performance, especially when using a high similarity threshold.
Blockhash is the only algorithm that does not resize images before hashing.Nearest resizing algorithm can be up to five times faster than other methods but may produce worse results.This tool finds similar videos using perceptual hashing, similar to the Similar Images feature.
Requirements
Process
This tool detects corrupted or invalid files that cannot be properly opened.
Supported file types
Process
Note: Since this tool relies on external libraries, false positives may occur (e.g., this issue). It is recommended to manually verify files before deletion.
This mode allows finding files whose content does not match their extension.
It works as follows:
źrebię.zip → zip7zMime::Archiverar, 7z, zip, p7exe and dll, may have similar byte signatures)In the "Proper Extension" column, the extension detected by the Infer library appears in parentheses, while extensions with the same MIME type are displayed outside.
This tool finds files with problematic names that may cause issues on different operating systems or filesystems.
It can detect multiple naming problems:
file.JPG instead of file.jpgdocument😀.txt file.txt or file.txt файл.txt, 文档.doc_, -, , .)file___name.txt, doc---final.pdfEach check can be enabled or disabled independently. The tool suggests corrected filenames for all problematic files found.
This tool finds image files containing EXIF metadata and allows selective removal of tags.
Process
jpg, jpeg, jfif, png, tiff, tif, avif, jxl, webp, heic, heifOrientation, ColorSpace)This is useful for finding images with privacy-sensitive metadata like GPS coordinates, camera serial numbers, or editing software information.
This tool helps optimize video files by detecting optimization opportunities. It operates in two modes:
Identifies videos that could be re-encoded to a more efficient codec.
.mp4, .avi, .mkv)Detects videos with black bars or static content that can be cropped.
Additional features