aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/newbs_getting_started.md44
1 files changed, 36 insertions, 8 deletions
diff --git a/docs/newbs_getting_started.md b/docs/newbs_getting_started.md
index 9ebcccc77f..3299571376 100644
--- a/docs/newbs_getting_started.md
+++ b/docs/newbs_getting_started.md
@@ -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
+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 FIXME) 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