From 9c2ca00074784dbee27b459d71cfc8e75f47b976 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Fri, 28 Nov 2025 00:36:49 +1100 Subject: QMK CLI Environment bootstrapper (#25038) Co-authored-by: Joel Challis Co-authored-by: Pascal Getreuer --- docs/driver_installation_zadig.md | 2 +- docs/faq_build.md | 2 +- docs/newbs_getting_started.md | 66 ++++++++++++--------------------------- 3 files changed, 22 insertions(+), 48 deletions(-) (limited to 'docs') diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index 6fbcfa3bff..13b445b9b6 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -4,7 +4,7 @@ QMK presents itself to the host as a regular HID keyboard device, and as such re There are two notable exceptions: the Caterina bootloader, usually seen on Pro Micros, and the HalfKay bootloader shipped with PJRC Teensys, appear as a serial port and a generic HID device respectively, and so do not require a driver. -We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2, the `qmk_install.sh` script will have already installed the drivers for you. +We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2, the QMK CLI installation script will have already installed the drivers for you. ## Installation diff --git a/docs/faq_build.md b/docs/faq_build.md index 54ed576c70..05cb3251c8 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -44,7 +44,7 @@ Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices m Issues encountered when flashing keyboards on Windows are most often due to having the wrong drivers installed for the bootloader, or none at all. -Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_firmware` directory in MSYS2 or WSL) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package manually. +Re-running the QMK installation script (`curl -fsSL https://install.qmk.fm | sh`) or reinstalling the QMK Toolbox may fix the issue. Alternatively, you can download and run the [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) package manually. If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig) for more detailed information. diff --git a/docs/newbs_getting_started.md b/docs/newbs_getting_started.md index 1d2b60781b..1bc658b9b1 100644 --- a/docs/newbs_getting_started.md +++ b/docs/newbs_getting_started.md @@ -50,90 +50,64 @@ You will need to install [MSYS2](https://www.msys2.org). Once installed, close a Install the QMK CLI by running: ```sh -pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-python-qmk +curl -fsSL https://install.qmk.fm | sh ``` :::: ==== macOS -QMK maintains a Homebrew tap and formula which will automatically install the CLI and all necessary dependencies. - #### Prerequisites You will need to install Homebrew. Follow the instructions on https://brew.sh. -::: tip -If you are using an Apple Silicon machine, the installation process will take significantly longer because GitHub actions do not have native runners to build binary packages for the ARM and AVR toolchains. -::: - #### Installation Install the QMK CLI by running: ```sh -brew install qmk/qmk/qmk +curl -fsSL https://install.qmk.fm | sh ``` ==== Linux/WSL -::: tip -**Note for WSL users**: By default, the installation process will clone the QMK repository into your WSL home directory, but if you have cloned manually, ensure that it is located inside the WSL instance instead of the Windows filesystem (ie. not in `/mnt`), as accessing it is currently [extremely slow](https://github.com/microsoft/WSL/issues/4197). -::: - -#### Prerequisites - -You will need to install Git and Python. It's very likely that you already have both, but if not, one of the following commands should install them: - -* Debian / Ubuntu / Devuan: `sudo apt install -y git python3-pip` -* Fedora / Red Hat / CentOS: `sudo yum -y install git python3-pip` -* Arch / Manjaro: `sudo pacman --needed --noconfirm -S git python-pip libffi` -* Void: `sudo xbps-install -y git python3-pip` -* Solus: `sudo eopkg -y install git python3` -* Sabayon: `sudo equo install dev-vcs/git dev-python/pip` -* Gentoo: `sudo emerge dev-vcs/git dev-python/pip` - #### Installation -Install the QMK CLI by running: - -```sh -python3 -m pip install --user qmk -``` - -Alternatively, install the QMK CLI as a [uv](https://docs.astral.sh/uv/) managed tool, kept isolated in a virtual environment (requires uv to be installed): - -```sh -uv tool install qmk -``` - -#### Community Packages - -These packages are maintained by community members, so may not be up to date or completely functional. If you encounter problems, please report them to their respective maintainers. +::: info +Many Linux distributions are supported, but not all. Mainstream distributions will have best success -- if possible, choose either Debian or its derivatives (such as Ubuntu, or Mint), CentOS or its derivatives (such as Fedora, or Rocky Linux), and Arch or its derivatives (such as Manjaro, or CachyOS). +::: -On Arch-based distros you can install the CLI from the official repositories (NOTE: at the time of writing this package marks some dependencies as optional that should not be): +Install the QMK CLI by running: ```sh -sudo pacman -S qmk +curl -fsSL https://install.qmk.fm | sh ``` -You can also try the `qmk-git` package from AUR: +::: tip +**Note for WSL users**: By default, the installation process will clone the QMK repository into your WSL home directory, but if you have cloned manually, ensure that it is located inside the WSL instance instead of the Windows filesystem (ie. not in `/mnt`), as accessing it is currently [extremely slow](https://github.com/microsoft/WSL/issues/4197). +::: -```sh -yay -S qmk-git -``` +::: warning +Any QMK packages provided by your distribution's package manager are almost certainly out of date. It is strongly suggested the installation script above is used instead. +::: ==== FreeBSD #### Installation +::: warning +FreeBSD support is provided on a best-effort basis by the community instead of the QMK maintainers. It is strongly suggested that you use either Windows, macOS, or a supported distribution of Linux instead. +::: + Install the FreeBSD package for QMK CLI by running: ```sh pkg install -g "py*-qmk" ``` -NOTE: remember to follow the instructions printed at the end of installation (use `pkg info -Dg "py*-qmk"` to show them again). +::: info NOTE +Remember to follow the instructions printed at the end of installation (use `pkg info -Dg "py*-qmk"` to show them again). +::: ::::: -- cgit v1.2.3