shuakami/qq-chat-exporter: Export QQ Chat History to HTML, JSON, TXT and Excel

What qq-chat-exporter Solves, and Who Actually Needs It

QQ keeps conversation history inside its own client and account. There is no supported way to pull a group's messages, images and stickers into a folder you control. qq-chat-exporter exists to close that gap. The README describes it as a tool that reads friend and group chat records on your own computer and saves them locally, with export to HTML, JSON, TXT and Excel, plus separate download of images, videos and sticker files referenced in those chats.

The intended user is someone who wants an archive rather than a live client. That includes people leaving a group and wanting the history first, researchers who need message data in a structured file, and anyone who wants to keep a personal record without depending on QQ's own retention. The privacy claim is the selling point: the README states that all reading and parsing happens on your machine, that the project runs no server, and that nothing is uploaded. That claim is architecturally plausible because the tool talks to a locally running QQ protocol layer rather than a remote API, but it is still a claim you should verify against the code paths you enable.

One boundary is worth stating early. This is not a QQ client replacement and not a message sync service. It reads what the local login can see and writes files. If your requirement is continuous two-way sync across devices, this is the wrong shape of tool.

How It Works: NapCatQQ, a Local Port, and a Web Viewer

The repository credits NapCatQQ as the framework underneath. NapCatQQ is a QQ protocol implementation, and the exporter sits on top of it: the login step in the README is a QQ QR scan, which is how NapCatQQ authenticates. Once that login is live, the exporter can enumerate conversations and pull message payloads.

The delivery surface is a local web interface. The README's quick start tells you to open `http://localhost:40653/qce` after login, and the shell mode prints a one-click login link to the console with a token. Port 40653 is fixed in the documented flow, so a second instance or another service on that port will collide. The Docker path exposes the same idea from a container: `docker compose up -d` starts a service named `napcat-qce`, and `docker logs -f napcat-qce` is where the login QR code and token appear.

The top-level repository layout shows the split: `qq-chat-export-core/` for the export logic, `qq-chat-export-server/` for the serving layer, and three separate viewer directories (`qce-viewer/`, `qce-chunked-viewer/`, `qce-v4-tool/`). The chunked viewer name suggests large exports are handled in pieces rather than loaded whole, which matters once a group has years of media. The README also mentions scheduled exports, so the tool can run repeatedly rather than only on demand. The primary language is Rust, with Electron and JavaScript in the topic list, which matches a Rust core wrapped in a desktop shell.

Installing qq-chat-exporter on Windows, macOS and Linux

The recommended path on Windows is the one-click installer from the Releases page. Download it, run it, scan the QQ login QR code, then open the local viewer. The README gives this as three steps and states that the interface is served at `http://localhost:40653/qce`.

For shell mode on Windows, Linux and a macOS Apple Silicon preview, the README points to a platform archive on the Releases page and two launchers. Run the launcher for your platform, scan the QR code, and the console prints a one-click login link. If you prefer to open the browser yourself, the token is in that same console output.

# Windows
launcher-user.bat

# Linux / macOS
./launcher-user.sh

The macOS note is specific: only an Apple Silicon (arm64) preview package is published, and QQ must be fully quit before launch. There is no documented Intel Mac build.

The Docker route avoids installing QQ at all and is documented for macOS including Apple Silicon, Linux and Windows. Clone the repository, enter the `docker` directory, and bring the compose file up. Then follow the logs for the QR code and token.

git clone https://github.com/shuakami/qq-chat-exporter.git
cd qq-chat-exporter/docker
docker compose up -d

# 查看登录二维码与 Token
docker logs -f napcat-qce

The README notes that Apple Silicon runs through Rosetta emulation, so the first start may be slower than on native hardware. A first real use is to log in, pick one low-stakes group, export it to JSON, and confirm the file opens and that media referenced in the chat actually landed on disk. That single test tells you whether the login, the parser and the downloader all work before you point it at a decade of history.

Where qq-chat-exporter Breaks or Is the Wrong Choice

The macOS constraint is the clearest limitation. The README says QQ must be completely quit before the shell build starts, and only an arm64 preview package exists. On an Intel Mac, the shell route is simply not offered; Docker is the documented alternative, and it runs through Rosetta on Apple Silicon, which the README itself flags as slower on first start.

Port 40653 is hardcoded in the documented URLs. The README does not document a configuration key for changing it, so if that port is taken the documented quick start will not work as written. That is a real friction point for anyone running other local services.

Login is QR-based and tied to a QQ account session. The README does not document what happens when that session expires, nor does it describe a rollback or resume behaviour for an export interrupted mid-run. If you are exporting a very large group, treat an interrupted run as an unknown until you test it yourself.

The tool is also the wrong choice if your goal is analysis rather than archiving. It writes files; it does not rank, search across accounts or produce statistics. The README links community projects for that, including QQChatAnalyzer and QQ-Chat-AI-Analyzer, which implies the author expects analysis to happen elsewhere. And if you need this on Android, the README lists no Android build at all.

qq-chat-exporter Compared with ChatLab and the NapCatQQ Ecosystem

The README's related-projects section is the honest map of alternatives. ChatLab is listed first, and the community project QCE2ChatLab exists specifically to convert qq-chat-exporter output into ChatLab's format. That tells you the relationship: qq-chat-exporter is the extraction layer, ChatLab is the downstream analysis and browsing layer. If your end goal is reading conversations in a polished interface with cross-chat search, going straight to ChatLab may skip a conversion step.

NapCatQQ is not a competitor but the foundation. The related list also includes `napcat-qce-python`, a Python client for the exporter, which means the exporter has an API surface other tools call rather than only a human-facing viewer. If you are automating exports, that Python project is the more relevant comparison than any standalone exporter.

Against a generic QQ export script, the difference is packaging. This project ships installers, a Docker compose file, a local web viewer and scheduled export, all under GPL-3.0. A one-off script gives you a file and nothing else. The trade-off is that you inherit the NapCatQQ login model and its platform constraints along with the convenience.

Licence, Maintenance and What an Upgrade Costs You

The licence is GPL-3.0, stated in the README's licence section and shown in the repository's licence badge. For private archiving this is unremarkable. If you fork the exporter, bundle it into a product, or ship a modified binary, GPL-3.0's copyleft terms attach to your distribution. That is a description of the licence, not legal advice; read the full text in the LICENSE file before you redistribute anything.

The repository is not archived and the last push was on 2026-09-18, six days before this writing. Releases are frequent: v6.3.0 on 2026-09-11, preceded by v6.2.10 and v6.2.9 on 2026-08-31. That cadence cuts both ways. You get fixes quickly, but the version numbers move in small increments, which suggests the interface and export formats are still being adjusted. Pin the release you validate against rather than tracking the newest tag, and re-check the export format after any upgrade if a downstream tool consumes the JSON.

The upgrade cost sits mostly in the viewer directories and the core crate. Because the repository carries three separate viewer implementations, the viewer you use may lag the core. The README does not document a migration path between major versions, so back up an existing export before upgrading if you cannot regenerate it.

Editorial conclusion

Adopt qq-chat-exporter if you are on Windows and want a local archive of QQ messages and media, or if you can run Docker and accept the NapCatQQ login flow. Do not adopt it if you need an Android client, since the README lists no Android build, or if you cannot fully exit QQ on macOS, where the documentation requires that before launch. Before committing, verify that the release page carries a build for your platform, that port 40653 is free on the machine that will run it, and that you are comfortable with GPL-3.0 obligations for anything you redistribute.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. shuakami/qq-chat-exporter on GitHub