frappe_docker installer breaks on Python 3.14 (pypika ast.Str error)

[Inayatullahshinwari]

Description of the issue

Running installer.py from the frappe_docker repository fails during environment setup and Frappe installation. The failure occurs while installing pypika==0.48.9, which is a dependency of Frappe v15, when using Python 3.14.

This results in repeated ModuleNotFoundError: No module named 'frappe' messages and ultimately a build failure. The root cause appears to be Python 3.14 incompatibility with pypika==0.48.9, due to the removal of ast.Str in newer Python versions.

Context information (for bug reports)

• Repository: frappe_docker
• Branch / Version: latest (using installer.py)
• Frappe version: v15.x (version-15 branch)
• Python version: 3.14.2
• OS / Environment: Docker container (frappe_docker)
• Installation method: ./installer.py
• Bench version: 5.28.0 (update available to 5.29.0)

Steps to reproduce the issue

1. Clone the frappe_docker repository.
2. Enter the development container /workspace/development$ .
3. Run the installer: ./installer.py
4. Virtual environment is created and Frappe installation starts.
5. Installation fails while building pypika==0.48.9.

Observed result

• The installer fails during the Frappe installation process.
• Dependency installation stops while building pypika==0.48.9.
• The build process raises the following errors:

  AttributeError: module 'ast' has no attribute 'Str'

• Multiple warnings/errors appear stating:

  ModuleNotFoundError: No module named 'frappe'

• The site is not created and the bench setup remains incomplete.

Expected result

• installer.py completes successfully without errors.
• All Frappe dependencies, including pypika, are installed correctly.
• The virtual environment is created and configured properly.
• Bench initialization and site creation complete successfully.
• A fully working Frappe development environment is available.

Stacktrace / full error message if available

frappe@dc4ea650c3e9:/workspace/development$ ./installer.py 

Setting Up Environment
$ uv venv env --seed --python python3
Using CPython 3.14.2 interpreter at: /home/frappe/.pyenv/versions/3.14.2/bin/python3
Creating virtual environment with seed packages at: env
warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
         If the cache and target directories are on different filesystems, hardlinking may not be supported.
         If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.
 + pip==25.3
Activate with: source env/bin/activate
Getting frappe
$ git clone https://github.com/frappe/frappe --branch version-15 --depth 1 --origin upstream
Cloning into 'frappe'...
remote: Enumerating objects: 3393, done.
remote: Counting objects: 100% (3393/3393), done.
remote: Compressing objects: 100% (3060/3060), done.
remote: Total 3393 (delta 406), reused 1950 (delta 221), pack-reused 0 (from 0)
Receiving objects: 100% (3393/3393), 17.41 MiB | 1.11 MiB/s, done.
Resolving deltas: 100% (406/406), done.
Installing frappe
$ uv pip install --quiet --upgrade -e /workspace/development/frappe-bench/apps/frappe  --python /workspace/development/frappe-bench/env/bin/python
  × Failed to build `pypika==0.48.9`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)

      [stderr]
      Traceback (most recent call last):
        File "<string>", line 14, in <module>
          requires = get_requires_for_build({})
        File "/home/frappe/.cache/uv/builds-v0/.tmpYg8Gkn/lib/python3.14/site-packages/setuptools/build_meta.py", line 331, in
      get_requires_for_build_wheel
          return self._get_build_requires(config_settings, requirements=[])
                 ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/home/frappe/.cache/uv/builds-v0/.tmpYg8Gkn/lib/python3.14/site-packages/setuptools/build_meta.py", line 301, in _get_build_requires
          self.run_setup()
          ~~~~~~~~~~~~~~^^
        File "/home/frappe/.cache/uv/builds-v0/.tmpYg8Gkn/lib/python3.14/site-packages/setuptools/build_meta.py", line 512, in run_setup
          super().run_setup(setup_script=setup_script)
          ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/home/frappe/.cache/uv/builds-v0/.tmpYg8Gkn/lib/python3.14/site-packages/setuptools/build_meta.py", line 317, in run_setup
          exec(code, locals())
          ~~~~^^^^^^^^^^^^^^^^
        File "<string>", line 38, in <module>
        File "<string>", line 20, in version
      AttributeError: module 'ast' has no attribute 'Str'

      hint: This usually indicates a problem with the package or the build environment.
  help: `pypika` (v0.48.9) was included because `frappe` (v15.96.0) depends on `pypika==0.48.9`
Error occured during app install: uv pip install --quiet --upgrade -e /workspace/development/frappe-bench/apps/frappe  --python /workspace/development/frappe-bench/env/bin/python
INFO: A newer version of bench is available: 5.28.0 → 5.29.0
 Configuring Bench ... 
 Set db_host 
 Setting db_type to mariadb 
/workspace/development/frappe-bench/env/bin/python: Error while finding module specification for 'frappe.utils.bench_helper' (ModuleNotFoundError: No module named 'frappe')
 Set redis_cache to redis://redis-cache:6379 
/workspace/development/frappe-bench/env/bin/python: Error while finding module specification for 'frappe.utils.bench_helper' (ModuleNotFoundError: No module named 'frappe')
 Set redis_queue to redis://redis-queue:6379 
/workspace/development/frappe-bench/env/bin/python: Error while finding module specification for 'frappe.utils.bench_helper' (ModuleNotFoundError: No module named 'frappe')
 Set redis_socketio to redis://redis-queue:6379 for backward compatibility 
/workspace/development/frappe-bench/env/bin/python: Error while finding module specification for 'frappe.utils.bench_helper' (ModuleNotFoundError: No module named 'frappe')
 Set developer_mode 
/workspace/development/frappe-bench/env/bin/python: Error while finding module specification for 'frappe.utils.bench_helper' (ModuleNotFoundError: No module named 'frappe')
 Set db_host 
/workspace/development/frappe-bench/env/bin/python: Error while finding module specification for 'frappe.utils.bench_helper' (ModuleNotFoundError: No module named 'frappe')
 Creating Site development.localhost ... 
/workspace/development/frappe-bench/env/bin/python: Error while finding module specification for 'frappe.utils.bench_helper' (ModuleNotFoundError: No module named 'frappe')

[libprince]

@Inayatullahshinwari
For Frappe v15: Use Python 3.11.x
For Frappe v16: Use Pyhton 3.14.x

[DanielRadlAMR]

Devcontainers are meant to be used with the latest software versions; therefore, the latest Bench images already apply the Frappe v16 requirements.

However, you can easily use older Bench versions if needed.

[adithyaappu]

Issue is as libprice said, the Frappe 15 only supports python 3.11 to 3.13. It is just a one line in the documentation, so easy to miss. Few things that worked for us

1. Frappe now uses UV for Python dependency management. Use uv python install <version> to install a version between 3.11 and 3.13
2. Then use the command uv python pin <version> in the bench directory or parent directory. You can pin a global version also.
3. If a virtual environment is already created, (If you already have a bench directory, then there will be a venv folder inside) that need to be deleted and recreated. Delete the frappe-bench/venv directory To manually create you can use uv venv command.
4. Instead of uv python pin <version> you can try specifying the python version when creating venv, for example. uv venv --python 3.11.6 venv
5. Sometimes you may have to uninstall and reinstall the apps already present in the bench.

[DanielRadlAMR]

@adithyaappu doesn't just selecting an older bench image like v5.27.0 solve this?

[adithyaappu]

I think it should. Haven't tested though. Fixing things with UV is needed when some bug fixes for the bench from newer version is needed for an existing setup using Frappe 15.

[dankgarlic1]

@adithyaappu doesn't just selecting an older bench image like v5.27.0 solve this?

I tried this while setting up the helpdesk repo and ran into the Python 3.14 issue with bench:latest. Pinning the image to frappe/bench:v5.27.0 (Python 3.11) fixed it for me