Skip to content

Installation

Jump to bottom
knoinok edited this page May 7, 2026 · 2 revisions

Installation

quansheng_toolkit runs on Windows, macOS and Linux. The Windows build is distributed as a single self-contained .exe. macOS and Linux build from source (Python 3.10+).

Windows (recommended: single .exe)

The fastest path. No installer, no Python, no internet after download.

  1. Open Releases.
  2. Download quansheng-toolkit.exe from the latest tagged release (~71 MB).
  3. Move it wherever you like (Desktop, C:\Tools\, a USB stick) — it's a portable single binary.
  4. Double-click to launch.

Note

First launch — Windows SmartScreen warning. SmartScreen will show "Windows protected your PC — unrecognised publisher". Click More info → Run anyway. The binary isn't code-signed yet (signing certificates are paid; on the roadmap). If you'd rather verify the file before running, the GitHub Release page lists the SHA-256 of every uploaded asset.

Tip

The .exe bundle includes the Python interpreter, Qt, the toolkit code and all 9 bundled firmwares. Internet is only consulted if you click a release-link in one of the firmware info cards.

Updating

There is no auto-updater. To update: download the new .exe from Releases and replace the old one. Your settings (themes, last-used directories) are stored in the OS's standard config location (%APPDATA%\QuanshengToolkit\) and survive across updates.

Windows (from source)

For developers, or if you want to run a specific commit / branch.

git clone https://github.com/knoinok/quansheng_toolkit.git
cd quansheng_toolkit
py -3.13 -m pip install -r requirements.txt PySide6
py -3.13 -m quansheng_toolkit.gui

Python 3.10+ works (CI tests 3.11 / 3.12 / 3.13). Get Python from python.org — make sure "Add Python to PATH" is checked during install.

For a virtual environment (recommended if you have other Python projects):

py -3.13 -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt PySide6
python -m quansheng_toolkit.gui

macOS

brew install python@3.13
git clone https://github.com/knoinok/quansheng_toolkit.git
cd quansheng_toolkit
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt PySide6
python3 -m quansheng_toolkit.gui

If you don't have Homebrew: https://brew.sh.

Important

Apple Silicon vs Intel Macs. PySide6 has wheels for both — pip install PySide6 picks the right one automatically. No special steps needed.

Linux

Tested on Debian/Ubuntu, Arch, and Fedora.

Debian / Ubuntu

sudo apt install python3 python3-pip python3-venv
git clone https://github.com/knoinok/quansheng_toolkit.git
cd quansheng_toolkit
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt PySide6
python3 -m quansheng_toolkit.gui

Arch / Manjaro

sudo pacman -S python python-pip
# then same git clone + venv flow as above

Fedora / RHEL

sudo dnf install python3 python3-pip
# then same git clone + venv flow as above

Serial-port permissions

You need permission to access /dev/ttyUSB* or /dev/ttyACM*. Add yourself to the appropriate group:

sudo usermod -aG dialout $USER     # Debian/Ubuntu
sudo usermod -aG uucp $USER        # Arch/Fedora
# log out and back in (or reboot) for the group change to take effect

Stable USB-C device name (optional)

For a predictable /dev/quansheng_uvk1 symlink that survives reboots:

echo 'SUBSYSTEM=="tty", ATTRS{idVendor}=="36b7", ATTRS{idProduct}=="ffff", MODE="0660", GROUP="dialout", SYMLINK+="quansheng_uvk1"' | sudo tee /etc/udev/rules.d/99-quansheng.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

USB drivers

The radio's USB cable type determines whether you need a driver.

Cable Driver needed?
UV-K1 family (USB-C native, no adapter) No — uses the radio's own USB CDC, recognised out of the box on Windows 10+, macOS, Linux.
CH340 / CH9102 cable (typical UV-K5 family aftermarket cable, USB-A → SMA-style coaxial plug) Yes on macOS and Windows 7. Windows 10/11 ships drivers via Windows Update.

CH340/CH9102 driver downloads

Note

If you bought a "Genuine Quansheng" branded cable, it's almost certainly CH340 inside. Counterfeit-detection pop-ups some Windows hosts show ("Driver couldn't be loaded — counterfeit chip") are caused by old WCH driver versions; install the latest from the link above.

Verifying the install

After installing, run:

python -m quansheng_toolkit info

You should see something like:

Connected to /dev/ttyUSB0 (or COM3, /dev/cu.usbserial-XXX)
Firmware version: F4HWN_5.4.0

If info succeeds, the GUI will work too. Launch it with:

python -m quansheng_toolkit.gui

If info fails, see Troubleshooting & FAQ → Toolkit doesn't see the radio.

Next: Hardware Compatibility to confirm your radio is supported, then Flashing Firmware if you want to flash F4HWN.

quansheng_toolkit · Apache-2.0 · Open-source desktop toolkit for Quansheng UV-K1, UV-K1(8) v3 Mini Kong and UV-K5 V3 radios · Fully offline.

quansheng_toolkit

Home

Getting started

Operations

Reference

Source · Releases · Issues · Discussions

Clone this wiki locally