diff --git a/quickstart.md b/quickstart.md
index f9698b228..243aabcd9 100644
--- a/quickstart.md
+++ b/quickstart.md
@@ -1,19 +1,40 @@
-# Quickstart — Electrum (running from source)
+# Quickstart - Electrum Purple from source
+
+This guide creates a complete local `.venv` on Ubuntu for:
+
+- desktop Qt GUI
+- QML GUI
+- hardware-wallet Python dependencies
+- tests and coverage
 
 ## System prerequisites
 
 ```bash
-sudo apt-get install git python3.12 python3.12-venv libsecp256k1-dev xvfb
+sudo apt update
+sudo apt install -y \
+  git python3 python3-venv python3-dev build-essential pkg-config automake libtool gettext \
+  libsecp256k1-dev libusb-1.0-0-dev libudev-dev libhidapi-dev libzbar0 \
+  libgl1 libegl1 libxkbcommon-x11-0 libxcb-cursor0 libxcb-xinerama0 \
+  libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 \
+  libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 qt6-wayland xvfb
 ```
 
-> `libsecp256k1-dev` avoids recompiling the C library locally.
-> `xvfb` is only needed to run QML tests without a physical display.
+Notes:
+
+- `libsecp256k1-dev` avoids recompiling secp256k1 via `electrum_ecc`.
+- `libzbar0` enables QR scanning/reading support.
+- `xvfb` is useful for GUI/QML tests on headless systems.
+- The `libxcb-*`, `libgl1`, `libegl1`, and `qt6-wayland` packages avoid common PyQt6 runtime errors on Ubuntu.
 
 ---
 
 ## 1. Clone the repository
 
----
+If you are already inside the repository, just run:
+
+```bash
+git submodule update --init --recursive
+```
 
 ## 2. Create and activate the virtual environment
 
@@ -22,29 +43,40 @@ python3 -m venv .venv
 source .venv/bin/activate
 ```
 
+Upgrade packaging tools:
+
+```bash
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install -r contrib/requirements/requirements-build-base.txt
+python -m pip install "Cython>=0.27"
+```
+
 ---
 
 ## 3. Install dependencies
 
-### Tests only (no GUI)
+### Complete development environment
 
 ```bash
-ELECTRUM_ECC_DONT_COMPILE=1 pip install -r contrib/requirements/requirements.txt \
-  "cryptography>=2.6" "dnspython[DNSSEC]>=2.2,<2.5" \
-  pytest coverage \
-  "pycryptodomex>=3.7" pyaes \
-  && ELECTRUM_ECC_DONT_COMPILE=1 pip install -e .
+ELECTRUM_ECC_DONT_COMPILE=1 python -m pip install -e ".[full,qml_gui,tests]"
+python -m pip install -r contrib/requirements/requirements-ci.txt
+python -m pip install pytest-xdist pillow
 ```
 
-### Tests + Qt/QML GUI (Android)
+What this installs:
+
+- base runtime dependencies from `contrib/requirements/requirements.txt`
+- `full`: Qt GUI, crypto, and hardware-wallet Python dependencies
+- `qml_gui`: PyQt6/Qt6 packages suitable for the QML GUI
+- `tests`: extra Python packages used by the test suite
+- `requirements-ci.txt`: `pytest`, `coverage`, and `coveralls`
+- `pytest-xdist`: optional parallel test execution with `-n auto`
+- `pillow`: optional image support used by some hardware-wallet/plugin flows
+
+Verify the main imports:
 
 ```bash
-ELECTRUM_ECC_DONT_COMPILE=1 pip install -r contrib/requirements/requirements.txt \
-  "cryptography>=2.6" "dnspython[DNSSEC]>=2.2,<2.5" \
-  pytest coverage \
-  "pycryptodomex>=3.7" pyaes \
-  "pyqt6~=6.10" "pyqt6-qt6~=6.10" \
-  && ELECTRUM_ECC_DONT_COMPILE=1 pip install -e .
+python -c "import PyQt6.QtCore, PyQt6.QtQml, PyQt6.QtQuick, PyQt6.QtMultimedia, electrum_ecc, cryptography; print('ok')"
 ```
 
 ---
@@ -55,14 +87,17 @@ ELECTRUM_ECC_DONT_COMPILE=1 pip install -r contrib/requirements/requirements.txt
 # Qt GUI (default)
 ./run_electrum
 
+# Qt GUI on BitcoinPurple network
+./run_electrum --bitcoinpurple -g qt
+
 # BitcoinPurple network
 ./run_electrum --bitcoinpurple
 
 # BitcoinPurple testnet
 ./run_electrum --bitcoinpurple_testnet
 
-# QML GUI (Android-style)
-./run_electrum --gui qml
+# QML GUI
+./run_electrum --bitcoinpurple -g qml
 
 # Text UI (terminal)
 ./run_electrum --gui text
@@ -71,6 +106,13 @@ ELECTRUM_ECC_DONT_COMPILE=1 pip install -r contrib/requirements/requirements.txt
 ./run_electrum daemon -d
 ```
 
+After the editable install, the generated command should also work while the venv is active:
+
+```bash
+electrum-purple --bitcoinpurple -g qt
+electrum-purple --bitcoinpurple -g qml
+```
+
 ---
 
 ## 5. Run tests
@@ -88,11 +130,27 @@ pytest tests/test_bitcoin.py -v
 # BitcoinPurple tests
 pytest tests/test_bitcoinpurple.py -v
 
-# blockchain + bitcoin + BitcoinPurple together
+# Blockchain + Bitcoin + BitcoinPurple together
 pytest tests/test_blockchain.py tests/test_bitcoin.py tests/test_bitcoinpurple.py -v
 
-# QML tests (requires PyQt6 and xvfb)
-xvfb-run pytest tests/qml/ -v
+# QML tests
+QT_QPA_PLATFORM=offscreen pytest tests/qml -v
+
+# QML tests on a headless system
+xvfb-run -a pytest tests/qml -v
+```
+
+Run tests with coverage:
+
+```bash
+# Full suite with coverage
+coverage run --source=electrum -m pytest tests -v
+coverage report -m
+coverage html
+
+# QML tests with coverage
+QT_QPA_PLATFORM=offscreen coverage run --source=electrum -m pytest tests/qml -v
+coverage report -m
 ```
 
 ---