hcxtools: converting WiFi captures into Hashcat and John the Ripper hashes

What hcxtools solves, and who it is actually for

A WiFi capture is not a hash file. A pcapng dump holds beacon frames, association exchanges, EAPOL four-way handshakes and PMKID material mixed together with unrelated traffic. Hashcat and John the Ripper want a defined text format instead, and the two formats differ. hcxtools exists to sit in that gap: the README describes it as "a small set of tools to convert packets from capture files to hash files for use with Hashcat or John the Ripper", and states that the tools are 100% compatible with both and endorsed by Hashcat. The stated purpose is self-assessment: convert your own dump so you can check whether the WLAN key or PMK was transmitted in a way you did not intend, or upload the raw dump to wpa-sec.stanev.org to see whether your AP or a client falls to common wordlists.

The audience is narrow and the README says so without softening it. It lists required knowledge: radio technology, electromagnetic-wave engineering, the 802.11 protocol, key derivation functions, the NMEA 0183 protocol, and Linux. It then states that hcxdumptool and hcxtools are not recommended for inexperienced users or newbies. That is an unusual thing for a project README to admit, and it should be read as a filter rather than modesty. If you cannot read an EAPOL message pair and tell which message is missing, this toolchain will produce files you cannot interpret.

Supported hash modes are listed in the README: Hashcat modes 4800, 5500, 2200x, 16100, 250x and 1680x, where the last two are marked deprecated, and John the Ripper modes WPAPSK-PMK, PBKDF2-HMAC-SHA1, chap, netntlm and tacacs-plus. The README recommends mode 22000 (22001) over the deprecated 2500 (2501) and 16800 (16801).

The toolchain: one converter, several filters

The repository root holds one C source file per tool: hcxpcapngtool.c, hcxhashtool.c, hcxpmktool.c, hcxpottool.c, hcxpsktool.c, hcxeiutool.c, hcxwltool.c, hcxhash2cap.c, wlancap2wpasec.c and whoismac.c. The README's workflow line reads: hcxdumptool -> hcxpcapngtool -> hcxhashtool (additional hcxpsktool/hcxeiutool) -> hashcat or JtR. That ordering is the architecture. hcxpcapngtool does the conversion from raw capture to Hashcat and JtR readable formats; everything after it operates on the resulting hash file rather than on packets.

That split matters when you plan a run. hcxhashtool filters hashes out of an HC22000 file based on user input, so it is where you drop networks you do not care about. hcxpsktool generates weak PSK candidates from hash files or user input, and hcxeiutool prepares the -E -I -U output of hcxpcapngtool for use with Hashcat plus rules or JtR plus rules. hcxpmktool calculates and verifies a PSK and/or a PMK, which is the piece you use to confirm a candidate rather than to search for one. hcxpottool handles the ASCII and several UTF formats of Hashcat's pot file, and hcxhash2cap goes the other direction, converting hash files back to cap.

Two tools reach the network. whoismac shows vendor information or downloads an OUI reference list, and wlancap2wpasec uploads multiple gzip-compressed pcapng, pcap and cap files to wpa-sec.stanev.org. Those are the only components that need libcurl, which is consistent with the Makefile, where hcxhashtool, wlancap2wpasec and whoismac each link CURL_LIBS.

Installing hcxtools on Linux and converting a first capture

On most distributions the README says hcxtools are available through the package manager, which is the shorter path. If you build the latest git head instead, the README asks that your distribution be updated to its latest version and that all header files and dependencies be installed first. The clone and build steps it gives are:

git clone https://github.com/ZerBea/hcxtools.git
cd hcxtools
make -j $(nproc)

Installation defaults to /usr/bin and needs super user rights. The README shows this form:

make install

If you prefer /usr/local/bin, the Makefile accepts a PREFIX override, and the README gives it as:

make install PREFIX=/usr/local

The Makefile sets PREFIX to /usr by default and computes BINDIR as $(DESTDIR)$(PREFIX)/bin, so the override lands where you would expect. The build itself uses pkg-config to locate openssl, libcurl and zlib; the README lists libopenssl 3.0 or newer, librt, zlib, libcurl 7.56 or newer and pkg-config as requirements, with a kernel of 5.15 or newer. gcc 16 is recommended and deprecated versions are not supported.

A first real use is the conversion step. hcxpcapngtool reads a capture and writes a hash file; the README notes that most output files are appended to existing files, with pcapng, pcap and cap as the exceptions. That append behaviour is worth remembering before a second run against the same output path. The README also warns not to merge dump files, because doing so will destroy hash values assigned by custom blocks. The README does not document a rollback procedure for a conversion that produced a file you did not want, so keep the output path distinct per capture.

Where hcxtools stops: cracking, WEP, WPS and decryption

The README has a section titled "What Don't hcxtools Do?" and it is the most useful part of the document for setting expectations. The tools do not crack WPA PSK related hashes; you use Hashcat or JtR for that. They do not crack WEP, where the README points to the aircrack-ng suite. They do not crack WPS, where it points to Reaver or Bully. They do not decrypt encrypted traffic, where it points to tshark or Wireshark. If your task is any of those four, hcxtools is the wrong tool and the README says so before you install anything.

There are two further limitations that matter more than they first appear. First, the tools do not perform NONCE ERROR CORRECTIONS; in case of packet loss you get a wrong PTK. That is a correctness boundary, not a performance one. A capture with missing frames can still convert cleanly and still yield a hash that will never match, and nothing in the conversion will flag it for you. Second, the README states that hcxtools are designed as analysis tools, meaning everything is converted by default and unwanted information must be filtered out. That is the opposite of a default-deny design, and it is why hcxhashtool exists in the workflow. Expect to filter, and expect the unfiltered file to be larger and noisier than what you feed to Hashcat.

Platform support is explicit: Windows, macOS, Android, emulators and wrappers are unsupported. The README recommends Arch Linux for notebooks and desktops and OpenWRT for small systems such as a Raspberry Pi or a WiFi router.

hcxtools versus aircrack-ng for capture-to-hash work

The natural comparison is aircrack-ng, which also converts captures and also cracks WPA, and the README itself points to it for WEP. The difference in approach is scope. aircrack-ng is a suite that spans capture, conversion, cracking and WEP work in one project. hcxtools is deliberately one half of a pair: it converts, and it hands off. The README's workflow starts at hcxdumptool and ends at hashcat or JtR, with hcxtools occupying the middle, and the README advises keeping the version of hcxpcapngtool aligned with the version of hcxdumptool. That alignment requirement is a direct consequence of the split: two projects that must agree on a format can drift apart, and the README treats version matching as the user's responsibility.

A second difference is format focus. hcxtools targets Hashcat mode 22000 and the John the Ripper formats listed in the README, and it recommends 22000 over the deprecated 2500 and 16800. It also carries hcxpottool for Hashcat pot file formats and hcxhash2cap for the reverse conversion, which a general-purpose suite does not provide. If your pipeline is already built around Hashcat 22000 and you want the pot file and the hash file handled by the same project, that is the concrete argument for hcxtools. If you want one binary that captures and cracks without a version-matching step, the split design works against you.

The README does not compare itself to aircrack-ng on conversion quality, and there are no benchmark numbers in the README. The choice comes down to which half of the pipeline you want to own.

Maintenance, licence and the cost of staying current

The repository is not archived, and the last push was on 2026-09-25. Releases are frequent: 7.0.1 on 2025-08-17, 7.1.0 on 2026-02-01 and 7.1.2 on 2026-02-08. The Makefile pins PRODUCTION_VERSION to 7.1.2 and PRODUCTION_YEAR to 2026, and when the PRODUCTION flag is 0 it derives VERSION_TAG from git describe --tags, falling back to the production version. So a build from a clone without tags will still report a version rather than failing.

The README notes that this branch is pretty closely synced to the Hashcat and John the Ripper repositories. That is a maintenance statement with a cost attached: hcxtools tracks two external projects, and a format change in either one is a reason for the next release. The README's own instruction to keep hcxpcapngtool and hcxdumptool versions matched means an upgrade of one implies an upgrade of the other. Budget for that pairing rather than treating hcxtools as a component you set and forget.

The licence is MIT, per the repository, with license.txt at the root. MIT is permissive and imposes no copyleft obligation on your own code, but the tools link against OpenSSL, libcurl and zlib, whose own terms apply to those libraries. This is a description of the project's licence, not legal advice; if you redistribute binaries, review the licences of the linked libraries yourself. The README does not document a rollback path for a bad upgrade, so pinning a release tag before building is the practical precaution.

Editorial conclusion

Adopt hcxtools if you already work on Linux with hcxdumptool and Hashcat or John the Ripper, and you want one converter between a capture and a hash file. Do not adopt it if you need Windows, macOS or Android support, or if you expect the tool to recover a PSK for you: the README states the tools do not crack WPA PSK related hashes. Before you build, verify that your kernel is 5.15 or newer, that libopenssl 3.0 or newer and libcurl 7.56 or newer are present, and that the hcxpcapngtool version matches your hcxdumptool version.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. ZerBea/hcxtools on GitHub