# WxCleaner: a WeChat duplicate file cleaner that moves rather than deletes

> WxCleaner is a small Python desktop tool for the one problem every WeChat user eventually has, a receive directory full of the same file several times over. It finds duplicates with a three stage hashing scan, shows them in a sortable list, and puts the losers in the system trash instead of deleting them, with a second confirmation before anything moves.

**yqxie1991/WxCleaner** — 微信重复文件清理工具。采用智能哈希算法极速识别重复文件，支持可视化预览与安全删除（移至回收站）。

- Repository: https://github.com/yqxie1991/WxCleaner
- Website: https://github.com/yqxie1991/WxCleaner/releases
- Stars: 1,223 · Forks: 121
- Language: Python
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/yqxie1991-wxcleaner

## Three stages of hashing, and why the first one is free

The scanning strategy is the part of this tool worth understanding, and the README calls it a smart three stage scan. The first stage compares file sizes, which costs nothing but a directory listing, and everything that differs in size cannot be a duplicate. The second stage computes a partial hash over the head of each file, which is enough to separate almost all of the candidates that survived the first filter, and it reads a small fraction of each file. Only the files that still look identical go to the third stage, the full hash, which reads everything. The README's claim is that this greatly reduces disk I/O, identifies duplicates very quickly, and still reaches 100 percent accuracy, and the accuracy part is the interesting bit, because a partial hash alone is a heuristic while a full hash is a fact, and the three stage design gets both properties as long as the last stage is not skipped. The implementation lives in a `scanner.py` module separate from the interface.

## Nothing is deleted, and the decision of what to keep is made for you

The cleanup mechanism is the safety argument for the whole tool. The README is explicit that files are not physically and permanently deleted, but are safely moved to the system recycle bin or trash through the `send2trash` package, precisely to prevent mistakes. The screenshot-oriented workflow in the usage guide follows from that, with a second confirmation dialog before the move, a progress dialog that uses multiple threads concurrently, and the ability to abort safely at any point. The choice of which copy survives is made automatically after the scan, with the tool marking the items it suggests deleting and, by default, keeping the file whose path is shorter. That is a heuristic and it is the one place a user has to think, because the shortest path is not always the copy you want, for instance when the longer path is in a folder you use and the shorter one is a leftover from a different chat. You can adjust the selection by hand, or select all duplicates and then adjust, and the interface shows the index, path, size, modification time and status of every file, with sorting by clicking a column header and a right click that opens the file in the system file manager.

## A tkinter interface dressed for the desktop

The user interface is built on ttkbootstrap, which sits on top of Tkinter, and the README describes the result as a modern flat interface that is pleasant to use and supports dark and light themes. That choice of toolkit is worth noting for a tool that has to run everywhere, because Tkinter ships with Python itself and needs no runtime beyond the interpreter, while the visual language is handled by the ttkbootstrap theme layer. The cross platform work shows up in the details, with the interface fonts adapting per platform, using Microsoft YaHei on Windows, PingFang on macOS and Source Han Sans on Linux, and with the ability to open a file's location in the native file manager. The repository splits the code into `wx_gui.py` for the interface, `scanner.py` for the scanning and hashing, `platform_utils.py` for the platform specific behaviour such as font selection and file manager integration, and `main.py` as the entry point.

## It knows where WeChat keeps its files

The path handling is the feature that makes this a WeChat tool rather than a general duplicate finder. On startup the program tries to detect and prefill the default WeChat file storage directory for the platform it is running on, and you can also pick a folder yourself with a browse button. The README gives the usual locations, which are worth repeating because they are the first thing that goes wrong on a new machine. On Windows it is typically the WeChat Files directory under Documents, shown as This PC then Documents then WeChat Files. On macOS it is a long path inside the application support directory of the com.tencent.xinWeChat container. On Linux the README says the location is a custom WeChat data or download directory. The macOS path in particular is the kind of string that is tedious to type, which is why the auto-detection earns its place.

## Two ways to run it, and one dependency that often goes missing

The quickest route is a prebuilt Windows executable, `WxCleaner.exe`, downloaded from the releases page and double clicked, with no Python environment to configure. The second route is to run it from source on any of the three platforms, which needs Python 3.8 or later, a virtual environment, the requirements installed and then `python main.py`. 

The source route, as the README gives it:

```bash
git clone https://github.com/yqxie1991/WxCleaner.git
cd WxCleaner
python -m venv venv
pip install -r requirements.txt
python main.py
```

The catch the README flags is Tkinter, which some Python installations do not include, and it lists the fix per distribution, with `brew install python-tk` for macOS with Homebrew, `sudo apt-get install python3-tk` for Ubuntu and Debian, `sudo dnf install python3-tkinter` for Fedora and RHEL, and `sudo pacman -S tk` for Arch Linux. The dependency list itself is two pinned packages, `send2trash` at 1.8.3 and `ttkbootstrap` at 1.10.1, which is a small surface for a tool that deletes things.

## Building your own executable, and the limits of the tool

If you want to build the Windows executable yourself, the README gives two commands, installing PyInstaller and then running it against the `WxCleaner.spec` file, after which the single file `WxCleaner.exe` appears in the `dist/` directory. The repository also contains a `WxCleaner_bundled.py` alongside `WxCleaner.spec` and an `icon.ico`. The limits of the tool are the ones the disclaimer covers, where the author says the tool is meant to help manage and clean redundant files, that although it provides a safe delete mechanism through the trash, you should confirm the contents and importance of the files before a large cleanup, and that the author accepts no responsibility for data loss caused by mistakes or by conflicts with third party software. The licence is MIT, the first release was 1.0.0 in January 2026 and 1.1.0 in August 2026 was a cross platform compatibility and stability update.

## Conclusion

Adopt WxCleaner if your WeChat receive directory has grown into a duplicate farm and you want a visual way to see what is repeated before you remove anything. Do not run it over a directory that mixes chat attachments with files you still need, because the tool's default policy is to keep the copy with the shorter path, which is a heuristic rather than a judgement, and the README's own disclaimer says to confirm the contents and importance of files before a large cleanup. Before the first run, check that Tkinter is available on your Python, since a Homebrew or distribution Python often omits it, and note that on macOS and Linux the tool finds the WeChat directory itself while on Windows the usual location is the Documents folder. The licence is MIT, the current release is 1.1.0 from 2026-08-20, and the last push was the same day.

## FAQ

### How does WxCleaner find duplicate files without reading everything?

It uses a three stage scan: file size first as a free pre-filter, then a partial hash over the head of each file, then a full hash only for the files that still look identical. The README says this greatly reduces disk I/O while keeping detection accurate.

### Does WxCleaner delete files permanently?

No. Files are moved to the system recycle bin or trash through the `send2trash` package rather than being physically deleted, there is a second confirmation dialog before the move, and the progress dialog can be aborted safely.

### Why does WxCleaner fail to start on my Linux or macOS machine?

Usually because your Python has no Tkinter. The README lists the fix per distribution, with `brew install python-tk` on macOS with Homebrew, `sudo apt-get install python3-tk` on Ubuntu and Debian, `sudo dnf install python3-tkinter` on Fedora and RHEL, and `sudo pacman -S tk` on Arch Linux.

### Which copy does WxCleaner keep when it finds duplicates?

After the scan it marks the duplicates it suggests deleting and, by default, keeps the file whose path is shorter. You can change the selection by hand before confirming, and the list shows the index, path, size, modification time and status of every file with sorting by column and a right click that opens the location in the system file manager.

## Sources

- [License: MIT](https://github.com/yqxie1991/WxCleaner/blob/main/LICENSE)
- [Project website](https://github.com/yqxie1991/WxCleaner/releases)
- [README](https://github.com/yqxie1991/WxCleaner/blob/main/README.md)
- [Releases](https://github.com/yqxie1991/WxCleaner/releases)
- [yqxie1991/WxCleaner on GitHub](https://github.com/yqxie1991/WxCleaner)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yqxie1991-wxcleaner