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 2 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
44 changes: 36 additions & 8 deletions docs/newbs_getting_started.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,21 +101,49 @@ 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
waffle87 marked this conversation as resolved.
Show resolved Hide resolved
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):

```
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
```

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):
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:

```sh
sudo pacman -S qmk
```
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