A desktop viewer for your personal Pokémon collection. HexDex reads individual Pokémon files exported from PKHeX and displays them in a searchable collection with artwork, stats, moves, evolution chains, notes, tags, and favourites.
Supports .pk1 through .pk7 files, covering Generations 1–7. HexDex views exported files; it does not edit them or open complete game saves.
Website: tariqmk.github.io/HexDex
- Search by species name or nickname, and filter by type, generation, tags, favourites, shinies, legendaries, or eggs.
- Sort your collection by Pokédex number, level, name, or shiny status.
- Inspect stats, IVs/DVs, EVs, moves, nature, trainer details, and evolution chains.
- Switch between multiple Pokémon of the same species and generation using variant tabs.
- Add notes and tags, mark favourites, and apply tags to multiple Pokémon at once.
- Scan subfolders and export collection data to CSV.
- Follow generation-specific links to Serebii for more information.
- Reuse locally cached Pokémon data and artwork after the initial download.
- Follow scan progress in a compact activity panel beneath the loading message.
- Find the installed build version beside the HexDex logo, and select it to check for a newer release.
GitHub Actions builds downloadable packages for Windows (x64), Linux (x64), and macOS (Apple Silicon only).
Download the package for your operating system from GitHub Releases, then extract it. Only published releases are available publicly.
| Platform | Package | Launch |
|---|---|---|
| Windows x64 | HexDex-vX.Y.Z-windows-x64.zip |
Open HexDex/HexDex.exe |
| Linux x64 | HexDex-vX.Y.Z-linux-x64.tar.gz |
Run ./HexDex/HexDex from the extracted directory |
| macOS Apple Silicon | HexDex-vX.Y.Z-macos-arm64.zip |
Open HexDex.app |
X.Y.Z is the release version. Each release also includes SHA256SUMS.txt for checking download integrity.
Extract the entire package. Windows and Linux builds need their accompanying _internal folder. Packaged builds include their Python runtime, so users do not need to install Python separately.
The macOS package is not signed with an Apple Developer certificate or notarised. macOS may require approval in System Settings → Privacy & Security before it can be opened. Intel Macs are not supported by this build.
Linux builds target Ubuntu 22.04 or newer compatible distributions and require a graphical desktop plus the system libraries used by Qt. Other Linux distributions may need additional packages.
- Export individual Pokémon files from PKHeX into a folder.
- Open HexDex and choose that folder using Browse, or paste its path.
- Enable Subfolders if your collection spans multiple folders.
- Click Scan. The first scan downloads Pokémon information and artwork, so it requires an internet connection and may take a while.
- Use the search and filters to browse your collection, then click a card to see its details.
Previously cached information and artwork can be used offline. Scanning Pokémon whose information has not been cached still requires an internet connection. Serebii links also require internet access.
During a scan, a small panel appears beneath the loading message in the centre of the collection area. It updates about once a second with files processed, elapsed time, and the current download, including how long the request has been waiting.
Scan activity shows the four most recent events, including download failures. You can collapse it for a quieter display. The panel disappears when the collection loads and remains visible if the scan fails.
First scans can take longer because HexDex downloads species information, moves, abilities, evolution chains, and artwork sequentially. The file count advances when each file finishes processing, so it may pause while several downloads complete for one Pokémon. The Scan button is disabled during a scan to prevent overlapping scans.
The small label beside the HexDex logo shows the packaged release version, for example v1.8.5. Local Python runs show Development build. Draft and public packages carry the same version; publishing a draft does not change its contents.
- Select the version label beside the HexDex logo.
- Read the result in the Check for updates dialog.
- If a newer release is available, select Open release page to download it in your browser.
HexDex does not download or install updates itself. It never checks automatically.
Each exported file has its own notes, tags, and favourite status. Use the detail panel to edit notes and tags; they save automatically when you leave the note field or add or remove a tag, and a Saved label confirms it. To tag several Pokémon at once, click Select, choose their cards, and apply a tag.
Keep filenames unique across scanned subfolders: personal annotations are currently associated with filenames, so files sharing the same name can share annotations.
Click Export CSV to export the loaded collection. Choose where to save the file using the Save As dialog. The export includes Pokémon details, stats, moves, notes, tags, and favourites.
HexDex stores downloaded information, artwork, and personal annotations in a local cache/ folder. In a packaged build, this folder is created beside the executable, so keep the application somewhere it can write files.
Back up cache/notes.json. It contains your notes, tags, and favourites and cannot be recreated by downloading Pokémon data. When replacing the application with a newer build, preserve your cache folder and personal annotations.
The cache, Python environment, and generated executables are excluded from the source repository.
HexDex has no accounts, telemetry, or analytics. Your notes, tags, and favourites stay in the local cache/ folder. HexDex reads your Pokémon files and never changes them.
HexDex connects to the internet only for these features:
- Scan: downloads Pokémon information from PokéAPI (pokeapi.co) and artwork from GitHub (raw.githubusercontent.com) that is not yet cached.
- Serebii links: open serebii.net in your browser when you select them.
- Check for updates: when you select the version number, the app asks GitHub (api.github.com) for the latest release. It sends nothing else and nothing is downloaded.
The HexDex website loads no third-party fonts, analytics, or trackers. It asks GitHub (api.github.com) for the latest release to show the version and download links.
- Supported inputs are PKHeX-exported
.pk1–.pk7files; later generations and complete save files are not supported. - Held items are displayed for Generations 2–4 where a recognised mapping exists. Generation 5–7 held items are not currently displayed.
- Folder browsing and CSV saving use dialogs on the computer running HexDex. The desktop application is the primary way to use these features.
The application uses Python, Flask, and pywebview with the Qt backend. The interface uses HTML, CSS, and JavaScript without a separate frontend build step.
The icon master is assets/icons/hexdex_icon.svg. To rebuild the icon formats, the banner and the social card after a change:
- Edit
assets/icons/hexdex_icon.svg, or the name, tagline and colours at the top ofassets/make_assets.py. - Run
venv\Scripts\python.exe assets\make_assets.py.
The script writes hexdex_icon.png, .ico and .icns to assets/icons/, banner.png and social-card.png to docs/images/, and icon.svg and apple-touch-icon.png to docs/. To use the social card on GitHub, open the repository, select Settings, then under General go to Social preview. Select Edit > Upload an image and choose docs/images/social-card.png.
- Run
venv\Scripts\python.exe assets\make_screenshots.py. - Check the four images in
docs/images/before you commit them.
The script opens the real interface with 25 made-up sample Pokémon and saves the collection and detail views in light and dark. It keeps its settings and data in Meta/screenshot-cache/, so your own collection, notes and folders do not appear.
Note: The first run downloads PokéAPI information and artwork for the sample species. Later runs work offline.
The website is docs/index.html, docs/style.css and docs/app.js. It has no build step. GitHub Pages serves docs/ from the main branch, so a push to main updates the website.
To preview it locally:
- Run
venv\Scripts\python.exe -m http.server 8765 --bind 127.0.0.1 --directory docs. - Open
http://127.0.0.1:8765/.
The app previews on the website are built in HTML with sample data and generic silhouettes. The website contains no Pokémon artwork. To change the sample data, edit docs/app.js.
Note: The download links find release files by the end of their names, for example windows-x64.zip. If you rename release files, also change the ASSET patterns in docs/app.js. Until then, the links open the Releases page.
The workflow in .github/workflows/build.yml runs manually only. Pushing commits or tags does not trigger a build.
To build a draft or publish a release:
- Commit and push the changes you want to release. The workflow must be present on the repository's default branch for the manual run button to appear.
- Open Actions → Build and release HexDex and click Run workflow.
- Select the branch to build and choose the version increment:
- Patch (default): fixes, such as
1.8.2→1.8.3. - Minor: compatible new features, such as
1.8.2→1.9.0. - Major: breaking changes, such as
1.8.2→2.0.0.
- Patch (default): fixes, such as
- Choose draft (default) to test before publishing, or public to publish automatically after a successful build.
- Run the workflow. After all three platform builds succeed, it creates a versioned GitHub Release with the packages, checksums, and automatically generated release notes.
- For a draft, open it from the workflow summary or Releases page, test the packages, then edit the notes and click Publish release when ready.
The workflow calculates the next version from the highest existing stable vMAJOR.MINOR.PATCH version across repository tags and releases, including drafts. Drafts reserve their version so the next build receives a new number. With no matching tags, it starts from 0.0.0 before applying the chosen increment. Prerelease and unrelated tags are ignored. The increment is selected explicitly because the workflow cannot reliably infer whether changes are breaking.
Release runs are serialized to avoid duplicate version numbers. The tag points to the exact commit selected for the run. Build failures do not create a release or tag; publication failures may leave a draft that can be resumed by rerunning the failed job. Published releases are never overwritten. Draft releases are visible to repository users with write access; source code and Actions logs remain public in a public repository. Published release downloads remain available independently of the temporary Actions artifacts, which are retained for 30 days.
Runtime dependencies are listed in requirements.txt. The workflow installs PyInstaller and defines its packaging options directly, including the templates, Qt backend, and application icons (.ico for Windows, .icns for macOS, and the PNG window icon). It does not depend on the local spec in the ignored Meta/ folder. Generated build output belongs in downloadable build packages rather than source commits.
Actions embeds the calculated version in build-version.json and checks that it matches the release version before packaging. Both version calculation and release creation have the repository permission needed to see draft releases; platform build jobs retain read-only repository access.
For local development checks, run venv\Scripts\python.exe launch.py on Windows (or use the local start.bat). This exercises the desktop interface, but packaged downloads still need testing on their target operating systems before publishing.
Run the parser tests with venv\Scripts\python.exe -m unittest discover -s tests. The tests use generated sample files. To also check real exports, put .pk1–.pk7 files in Meta/test-pokemon/. That folder is git-ignored, so the files stay private.
HexDex/
├── app.py # Backend, Pokémon parsing, and local storage
├── launch.py # Desktop window launcher
├── requirements.txt # Runtime dependencies
├── .github/
│ └── workflows/
│ └── build.yml # Windows, Linux, and Apple Silicon builds
├── templates/
│ └── index.html # Application interface
├── assets/
│ ├── icons/ # Icon master (SVG) and its PNG, ICO and ICNS files
│ ├── make_assets.py # Builds the icons, banner and social card
│ └── make_screenshots.py # Retakes the README screenshots with sample data
└── docs/ # GitHub Pages website
├── index.html, style.css, app.js
├── icon.svg, apple-touch-icon.png
└── images/ # Banner, social card and screenshots
Pokémon information and artwork are provided through PokéAPI. Additional information links point to Serebii. Pokémon files are exported using PKHeX.
HexDex is an unofficial fan project and is not affiliated with Nintendo, Game Freak, or The Pokémon Company.