Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Add venv instructions and remove community packages #24679

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 27 additions & 8 deletions docs/newbs_getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,21 +101,40 @@ Install the QMK CLI by running:
python3 -m pip install --user qmk
```

#### Community Packages
::: tip
With the introduction of [PEP 668](https://peps.python.org/pep-0668), Python package management tools like `pip` are no longer permitted to install Python packages globally on Linux distributions that have adopted this PEP. As a result, the above command may not work in such environments. To address this, recommended alternatives include using a Python virtual environment or utilising [QMK's Docker container](getting_started_docker) for managing dependencies.
:::

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.
:::: details Virtual Environment Setup
Acquire a local copy of the QMK Firmware repository (including submodules):

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):
```
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
```

```sh
sudo pacman -S qmk
Create a virtual environment. The following command will create a `.venv` directory in your current working directory. If you'd prefer to store the virtual environment elsewhere, adjust the path accordingly:

```
python3 -m venv .venv
```

You can also try the `qmk-git` package from AUR:
Activate the virtual environment. The following command works for most commonly used shells like Bash, ZSH, sh, etc. If you are using Fish, Nu, or something else, see the alternate activation scripts in `.venv/bin/`:

```sh
yay -S qmk-git
```
source .venv/bin/activate
```

Install the QMK CLI package:

```
pip install qmk
```
::: tip
Using a virtual environment means it will need to be activated each time you plan to use the utilities it provides (eg. `qmk` commands in this case).
:::

::::

==== FreeBSD

Expand Down
Loading