Fix incorrect document regarding pyodide auditwheel (#2752)

ryanking13 · web-flow · commit 95b4b79b96ba · 2026-03-03T16:55:56.000+09:00
* Fix incorrect document for pyodide

* Fix incorrect document for pyodide

* Fix test
diff --git a/docs/options.md b/docs/options.md
@@ -911,6 +911,10 @@ Default:
 - on macOS: `'delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel}'`
 - on Android: There is no default command, but cibuildwheel will add `libc++` to the
   wheel if anything links against it. Setting a command will replace this behavior.
+- on Pyodide: You can use `pyodide auditwheel repair --libdir /path/to/libraries --output-dir {dest_dir} {wheel}` command to repair the wheel.
+  Unlike other platforms, this command is not set by default as you need to explicitly
+  specify the library directory. You might not want to use the libraries in the system
+  directory, as they are not built for WASM and will not work.
 - on other platforms: `''`
 
 A shell command to repair a built wheel by copying external library dependencies into the wheel tree and relinking them.
@@ -938,12 +942,6 @@ Platform-specific environment variables are also available:<br/>
 
     [Delvewheel]: https://github.com/adang1345/delvewheel
 
-!!! tip
-    When using `--platform pyodide`, `pyodide build` is used to do the build,
-    which already uses `auditwheel-emscripten` to repair the wheel, so the default
-    repair command is empty. If there is a way to do this in two steps in the future,
-    this could change.
-
 #### Examples
 
 !!! tab examples "pyproject.toml"
diff --git a/docs/platforms.md b/docs/platforms.md
@@ -179,6 +179,17 @@ If there are pre-releases available for a newer Pyodide version, the `pyodide-pr
 
 Currently, it's recommended to run tests using a `python -m` entrypoint, rather than a command line entrypoint, or a shell script. This is because custom entrypoints have some issues in the Pyodide virtual environment. For example, `pytest` may not work as a command line entrypoint, but will work as a `python -m pytest` entrypoint.
 
+### Repairing wheels
+
+Unlike other platforms, cibuildwheel does not set a default [`repair-wheel-command`](options.md#repair-wheel-command) for Pyodide. If your package links shared libraries, you need to explicitly configure the repair command using [`pyodide auditwheel`](https://github.com/pyodide/auditwheel-emscripten):
+
+```toml
+[tool.cibuildwheel.pyodide]
+repair-wheel-command = "pyodide auditwheel repair --libdir /path/to/libraries --output-dir {dest_dir} {wheel}"
+```
+
+The `--libdir` option specifies the directory containing cross-compiled shared libraries for WASM. You should not use the system library directories (e.g. `/usr/lib`), as those libraries are not built for WebAssembly.
+
 
 ## Android {: android}
 
diff --git a/test/test_pyodide.py b/test/test_pyodide.py
@@ -146,6 +146,29 @@ def test_filter():
             "spam-0.1.0-cp312-cp312-pyodide_2024_0_wasm32.whl",
             "spam-0.1.0-cp313-cp313-pyodide_2025_0_wasm32.whl",
         ]
-        print("actual_wheels", actual_wheels)
-        print("expected_wheels", expected_wheels)
         assert set(actual_wheels) == set(expected_wheels)
+
+
+def test_pyodide_repair_wheel(tmp_path):
+    if sys.platform == "win32":
+        pytest.skip("pyodide-build doesn't work correctly on Windows")
+
+    project_dir = tmp_path / "project"
+    basic_project.generate(project_dir)
+
+    actual_wheels = utils.cibuildwheel_run(
+        project_dir,
+        add_args=["--platform", "pyodide"],
+        add_env={
+            "CIBW_REPAIR_WHEEL_COMMAND_PYODIDE": (
+                "pyodide auditwheel repair --libdir /path/to/libraries --output-dir {dest_dir} {wheel}"
+            ),
+        },
+        single_python=True,
+    )
+
+    # check that the expected wheels are produced
+    expected_wheels = [
+        "spam-0.1.0-cp312-cp312-pyodide_2024_0_wasm32.whl",
+    ]
+    assert set(actual_wheels) == set(expected_wheels)
