diff --git a/docs/building.md b/docs/building.md
index 190ad3c7b00..28fb3e01b9b 100644
--- a/docs/building.md
+++ b/docs/building.md
@@ -59,30 +59,28 @@ a number of hours to complete.
                         export PATH="/opt/homebrew/opt/python@3.14/libexec/bin:$PATH"
                     ```
                
-        1. Install gyp:
+        1. Install [gyp-next](https://github.com/nodejs/gyp-next) into a virtualenv and put it on your path:
             ```shell
-            wget https://bootstrap.pypa.io/ez_setup.py -O - | python3 -
-            git clone https://chromium.googlesource.com/external/gyp.git ~/tools/gyp
-            cd ~/tools/gyp
-            pip install .
+            python3 -m venv ~/.local/venvs/gyp-next
+            ~/.local/venvs/gyp-next/bin/pip install gyp-next
+            mkdir -p ~/.local/bin
+            ln -sf ~/.local/venvs/gyp-next/bin/gyp ~/.local/bin/gyp
             ```
-            1. Add `~/tools/gyp` to your path:
+            1. Make sure `~/.local/bin` is on your path (add this to your bash/zsh profile if needed):
                ```shell
-               export PATH="~/tools/gyp:$PATH"
+               export PATH="$HOME/.local/bin:$PATH"
                ```
-            1. If you have additional questions, consult [this guide](https://github.com/mogemimi/pomdog/wiki/How-to-Install-GYP).
-            1. If you encounter a `ModuleNotFoundError`, try installing setuptools on your system. For example:
-                ```shell
-               brew install python-setuptools
-               ```
-            1. Similarly, recent brew installations may result in **externally-managed-environment** errors. This can be addressed with `brew install pipx` and replacing the last line with `pipx install .`
-
-
-
-        1. Make sure your homebrew python's bin folder is on your path by updating your bash/zsh profile with the following:
-            ```shell
-            export PATH="$PATH:$(brew --prefix)/opt/python@3.9/Frameworks/Python.framework/Versions/3.9/bin"
-            ```
+            1. The virtualenv path must not contain spaces: gyp writes its Python path unquoted into the
+               generated ninja files. This rules out `pipx`'s default location on macOS
+               (`~/Library/Application Support/pipx`).
+            1. Don't use the old Chromium gyp (`chromium.googlesource.com/external/gyp`). It is unmaintained
+               and fails on current Python and Xcode versions.
+    1. If linking fails with `tapi error: malformed file ... unknown architecture`, the selected macOS SDK is
+       newer than your Command Line Tools linker. Check `xcrun --show-sdk-path`, and either update the
+       Command Line Tools or pin a matching SDK in your bash/zsh profile, e.g.:
+        ```shell
+        export SDKROOT=$(xcrun --sdk macosx26.5 --show-sdk-path)
+        ```
     #### Windows
     *Install windows build tools*
 
diff --git a/libs/README.md b/libs/README.md
index 28b883a87b9..e9b1a95a14b 100644
--- a/libs/README.md
+++ b/libs/README.md
@@ -10,7 +10,7 @@ This directory builds the required libraries for iOS, Android and desktop platfo
 
 ### Build dependencies
 
-* [GYP](https://github.com/mogemimi/pomdog/wiki/How-to-Install-GYP)
+* [gyp-next](https://github.com/nodejs/gyp-next) (see [building.md](../docs/building.md) for install instructions)
 * [ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages)
 * [Tcl](https://www.tcl.tk/software/tcltk/)
 
diff --git a/libs/build-all.sh b/libs/build-all.sh
index b9d3af01723..3d464783ea8 100755
--- a/libs/build-all.sh
+++ b/libs/build-all.sh
@@ -28,7 +28,7 @@ abspath () { case "${1}" in /*)printf "%s\\n" "${1}";; *)printf "%s\\n" "${PWD}/
 export -f abspath
 
 if ! [[ -x "$(command -v gyp)" ]]; then
-  echo 'Error: gyp needs to be installed and executable. See https://github.com/mogemimi/pomdog/wiki/How-to-Install-GYP for install instructions.' >&2
+  echo 'Error: gyp needs to be installed and executable. Install gyp-next (https://github.com/nodejs/gyp-next); see docs/building.md for instructions.' >&2
   exit 1
 fi