Installation fails on Python 3.13 due to missing distutils module (fs-ext compilation)

[masonjames]

WordPress Playground installation fails on systems with Python 3.13 due to the `fs-ext` package failing to compile. The error occurs because Python 3.13 removed the `distutils` module, which `node-gyp` depends on for native module compilation.

Error Details

Environment:

• Node.js: v24.2.0
• npm: 11.3.0
• Python: 3.13.5
• macOS: Darwin 24.5.0 (arm64)

Error Message:

npm error gyp ERR! stack Error: \`gyp\` failed with exit code: 1
npm error Traceback (most recent call last):
npm error   File \"/node_modules/node-gyp/gyp/pylib/gyp/input.py\", line 19, in <module>
npm error     from distutils.version import StrictVersion
npm error ModuleNotFoundError: No module named 'distutils'

Root Cause:

• Python 3.13+ removed the `distutils` module (PEP 632)
• `fs-ext` package requires native compilation via `node-gyp`
• `node-gyp` still depends on the removed `distutils` module
• `fs-ext` is used for file locking in the Node.js PHP WASM implementation

Solution

I fixed this for myself with Claude Code's help. I had to downgrade to Python 3.12 and install `setuptools` to provide the missing `distutils` module.

Figured it made sense to document it. Cool project!

[bgrgicak]

@ryanwelcher showed me an issue that could be related.
@ryanwelcher solved it by switching to an older version of the Playground CLI (I think 1.1.2, but I'm not sure).

Here are Ryan's logs:

~/install-test 	 npm install @wp-playground/cli
npm error code 1
npm error path /Users/user/repositories/install-test/node_modules/fs-ext
npm error command failed
npm error command sh -c node-gyp configure build
npm error CXX(target) Release/obj.target/fs_ext/fs-ext.o
npm error gyp info it worked if it ends with ok
npm error gyp info using node-gyp@10.1.0
npm error gyp info using node@20.18.3 | darwin | arm64
npm error gyp info find Python using Python version 3.9.6 found at "/Library/Developer/CommandLineTools/usr/bin/python3"
npm error gyp info spawn /Library/Developer/CommandLineTools/usr/bin/python3
npm error gyp info spawn args [
npm error gyp info spawn args '/Users/user/.nvm/versions/node/v20.18.3/lib/node_modules/npm/node_modules/node-gyp/gyp/gyp_main.py',
npm error gyp info spawn args 'binding.gyp',
npm error gyp info spawn args '-f',
npm error gyp info spawn args 'make',
npm error gyp info spawn args '-I',
npm error gyp info spawn args '/Users/user/repositories/install-test/node_modules/fs-ext/build/config.gypi',
npm error gyp info spawn args '-I',
npm error gyp info spawn args '/Users/user/.nvm/versions/node/v20.18.3/lib/node_modules/npm/node_modules/node-gyp/addon.gypi',
npm error gyp info spawn args '-I',
npm error gyp info spawn args '/Users/user/Library/Caches/node-gyp/20.18.3/include/node/common.gypi',
npm error gyp info spawn args '-Dlibrary=shared_library',
npm error gyp info spawn args '-Dvisibility=default',
npm error gyp info spawn args '-Dnode_root_dir=/Users/user/Library/Caches/node-gyp/20.18.3',
npm error gyp info spawn args '-Dnode_gyp_dir=/Users/user/.nvm/versions/node/v20.18.3/lib/node_modules/npm/node_modules/node-gyp',
npm error gyp info spawn args '-Dnode_lib_file=/Users/user/Library/Caches/node-gyp/20.18.3/<(target_arch)/node.lib',
npm error gyp info spawn args '-Dmodule_root_dir=/Users/user/repositories/install-test/node_modules/fs-ext',
npm error gyp info spawn args '-Dnode_engine=v8',
npm error gyp info spawn args '--depth=.',
npm error gyp info spawn args '--no-parallel',
npm error gyp info spawn args '--generator-output',
npm error gyp info spawn args 'build',
npm error gyp info spawn args '-Goutput_dir=.'
npm error gyp info spawn args ]
npm error gyp info spawn make
npm error gyp info spawn args [ 'BUILDTYPE=Release', '-C', 'build' ]
npm error In file included from ../fs-ext.cc:20:
npm error In file included from /Users/user/Library/Caches/node-gyp/20.18.3/include/node/node.h:73:
npm error /Users/user/Library/Caches/node-gyp/20.18.3/include/node/v8.h:21:10: fatal error: 'memory' file not found
npm error    21 | #include <memory>
npm error       |          ^~~~~~~~
npm error 1 error generated.
npm error make: *** [Release/obj.target/fs_ext/fs-ext.o] Error 1
npm error gyp ERR! build error 
npm error gyp ERR! stack Error: `make` failed with exit code: 2
npm error gyp ERR! stack at ChildProcess.<anonymous> (/Users/user/.nvm/versions/node/v20.18.3/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:209:23)
npm error gyp ERR! System Darwin 24.5.0
npm error gyp ERR! command "/Users/user/.nvm/versions/node/v20.18.3/bin/node" "/Users/user/.nvm/versions/node/v20.18.3/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "configure" "build"
npm error gyp ERR! cwd /Users/user/repositories/install-test/node_modules/fs-ext
npm error gyp ERR! node -v v20.18.3
npm error gyp ERR! node-gyp -v v10.1.0
npm error gyp ERR! not ok
npm error A complete log of this run can be found in: /Users/user/.npm/_logs/2025-06-26T10_14_21_031Z-debug-0.log

[adamziel]

@masonjames thank you so much for the detailed report! It seems related to #2316 – it sounds like depending on fs-ext is quite problematic. I wonder what are our options here 🤔 Displaying a clear error message with actionable next steps would be one – but requiring users to figure out a python version is quite inconvenient. Forking fs-ext with an alternative build tool would be one.

What if fs-ext was optional? Only consumers using multiple workers would install it?

@brandonpayton what do you think?

[adamziel]

It seems like node-gyp resolved that issue a while ago:

nodejs/node-gyp#2869

However, in my node_modules I still found node-gyp v9.4.1. Perhaps it's enough to upgrade that?

At the same time, @ryanwelcher's log says npm error gyp info using node-gyp@10.1.0. 🤔. Let's try enforcing the latest node-gyp version – perhaps that would suffice.

[brandonpayton]

What if fs-ext was optional? Only consumers using multiple workers would install it?

@brandonpayton what do you think?

@adamziel, that's a tough one. I wonder if we could make fs-ext install and usage conditional based upon Node.js version, maybe via a post-install hook and then dynamic import.

[brandonpayton]

Here is a PR to make the fs-ext dependency optional:
#2322

[adamziel]

This should be fixed in @wp-playground/cli 1.2.0 – @masonjames, @ryanwelcher, please let us know if it works for you now.

[masonjames]

confirmed! works great 👍

[ryanwelcher]

Late to the party here but wanted to confirm that 1.2.0 installs fine for me.