2 files changed, 41 insertions, 6 deletions

diff --git a/docs/newbs_getting_started.md b/docs/newbs_getting_started.md
index 13b25bf86..83df2f305 100644
--- a/docs/newbs_getting_started.md
+++ b/docs/newbs_getting_started.md
@@ -69,10 +69,21 @@ You will need to install Git and Python. It's very likely that you already have
 * Fedora / Red Hat / CentOS: `sudo yum install git python3 python3-pip`
 * Arch / Manjaro: `sudo pacman -S git python python-pip python-setuptools libffi`
 
-
 Install the global CLI to bootstrap your system:
 
-  `python3 -m pip install --user qmk` (on Arch-based distros you can also try the `qmk` package from AUR (**note**: it's maintained by a community member): `yay -S qmk`)
+`python3 -m pip install --user qmk` (on Arch-based distros you can also try the `qmk` package from AUR (**note**: it's maintained by a community member): `yay -S qmk`)
+
+### FreeBSD
+
+You will need to install Git and Python. It's possible that you already have both, but if not, run the following commands to install them:
+
+    pkg install git python3
+
+Make sure that `$HOME/.local/bin` is added to your `$PATH` so that locally install Python packages are available.
+
+Once installed, you can install QMK CLI:
+
+    python3 -m pip install --user qmk
 
 ## 3. Run QMK Setup :id=set-up-qmk
 
@@ -88,6 +99,12 @@ This is due to a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155)
 Sadly, Ubuntu reitroduced this bug and is [yet to fix it](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562).
 Luckily, the fix is easy. Run this as your user: `echo "PATH=$HOME/.local/bin:$PATH" >> $HOME/.bashrc && source $HOME/.bashrc`
 
+?>**Note on FreeBSD**:
+It is suggested to run `qmk setup` as a non-`root` user to start with, but this will likely identify packages that need to be installed to your
+base system using `pkg`. However the installation will probably fail when run as an unprivileged user.
+To manually install the base dependencies, run `./util/qmk_install.sh` either as `root`, or with `sudo`.
+Once that completes, re-run `qmk setup` to complete the setup and checks.
+
 ?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create your own fork and use `qmk setup <github_username>/qmk_firmware` to clone your personal fork. If you don't know what that means you can safely ignore this message.
 
 ## 4. Test Your Build Environment
diff --git a/util/freebsd_install.sh b/util/freebsd_install.sh
index 815759203..09669024c 100755
--- a/util/freebsd_install.sh
+++ b/util/freebsd_install.sh
@@ -1,7 +1,5 @@
 #!/bin/sh
-util_dir=$(dirname "$0")
-pkg update
-pkg install -y \
+packages=$(cat <<EOF
         git \
         wget \
         gmake \
@@ -13,9 +11,29 @@ pkg install -y \
         avr-libc \
         dfu-programmer \
         dfu-util \
+        avrdude \
         arm-none-eabi-gcc \
         arm-none-eabi-binutils \
         arm-none-eabi-newlib \
         diffutils \
         python3
-pip3 install -r ${util_dir}/../requirements.txt
+EOF
+)
+util_dir=$(dirname "$0")
+if [ $(id -u) = 0 ]; then
+        pkg update
+        pkg install -y ${packages}
+        echo ""
+        echo "Re-run the setup as your normal user to install the qmk python dependencies"
+        exit 1
+else
+        if command -v sudo > /dev/null 2>&1; then
+                sudo pkg update
+                sudp pkg install -y ${packages}
+        else
+                echo "Make sure you run setup as root first to install base OS dependencies..."
+                echo ""
+        fi
+
+        python3 -m pip install --user -r ${util_dir}/../requirements.txt
+fi