diff --git a/pyodide/README.md b/pyodide/README.md
new file mode 100644
index 0000000000..68853df8ab
--- /dev/null
+++ b/pyodide/README.md
@@ -0,0 +1,34 @@
+
+There are two ways to build pyodide ifcopenshell Python wrapper wheel.
+
+1. Using pyodide build system (`build_pyodide.yml` does it):
+
+- setup pyodide environment in `pyodide_root` folder - either by using image or build it from source - see https://pyodide.org/en/stable/development/building-from-sources.html
+- clone IfcOpenShell repo next to it to `IfcOpenShell` folder
+- create `packages/ifcopenshell` folder that will be used by pyodide build system
+- from `IfcOpenShell` move building recipe `pyodide/meta.yaml` to `packages/ifcopenshell`
+- run `pyodide build-recipes ifcopenshell --install`, it will
+    - execute `meta.yaml` recipe - it will:
+        - copy IfcOpenShell source to build folder `packages/ifcopenhell/build/ifcopenshell-0.8.0`
+        - build ifcopenshell and its dependencies
+        - note that rerunning `pyodide build-recipes` will remove previous build folder and rebuild all dependencies.  
+        The way to avoid it, if build fails, is to use `pyodide build-recipes-no-deps ifcopenshell --continue` instead.
+    - run `pyodide/setup.py` in `IfcOpenShell` root, producing a wheel in `IfcOpenShell/dist`
+    - copy that wheel to `packages/ifcopenshell/dist`
+    - `--install` it to current build envrionment
+        - copy the wheel next to `dist` folder (in root directory, next to `packages`)
+        - add wheel to `dist/pyodide-lock.json`
+
+2. Build it outside of pyodide system.
+
+Building inside pyodide build system should be preferred, option to build it outside is useful for debugging purposes,
+since it's pure cmake without any additional moving parts.
+
+- setup pyodide environment in `pyodide_root` folder, see above
+- clone IfcOpenShell repo next to it to `IfcOpenShell` folder
+- setup debug build environment using `source pyodide/debug_build_env.sh /path/to/pyodide_root`
+- run `python nix/build-all.py -wasm -py-313` in `IfcOpenShell`
+    - it will produce Python package in `IfcOpenShell/ifcopenshell`
+- move `IfcOpenShell/pyodide/setup.py` to `IfcOpenShell` root
+- run `pyodide build`
+    - it will produce a wheel in `IfcOpenShell/dist`
diff --git a/pyodide/debug_build_env.sh b/pyodide/debug_build_env.sh
new file mode 100755
index 0000000000..2d9759f30d
--- /dev/null
+++ b/pyodide/debug_build_env.sh
@@ -0,0 +1,10 @@
+#!/bin/bash
+if [ $# -ne 1 ]; then
+  echo "Usage: $0 <pyodide_root>"
+  exit 1
+fi
+export PYODIDE_ROOT=$(readlink -f "$1")
+export PATH="$PYODIDE_ROOT/emsdk/emsdk:$PYODIDE_ROOT/emsdk/emsdk/node/22.16.0_64bit/bin:$PYODIDE_ROOT/emsdk/emsdk/upstream/emscripten:$PATH"
+# build-all.py vars.
+export WASM_PYTHON_PATH="$PYODIDE_ROOT/cpython/installs/python-3.13.2"
+export WASM_TOOLCHAIN_FILE="$PYODIDE_ROOT/pyodide-build/pyodide_build/tools/cmake/Modules/Platform/Emscripten.cmake"
diff --git a/pyodide/meta.yaml b/pyodide/meta.yaml
index 8878f6d76f..595db2689f 100644
--- a/pyodide/meta.yaml
+++ b/pyodide/meta.yaml
@@ -3,6 +3,7 @@ package:
   version: 0.8.0
 
 source:
+  # meta.yaml is placed as `packages/ifcopenshell/meta.yaml`.
   path: ../../IfcOpenShell
 
 build: