Ewoks install bootstrap

[woutdenolf]

Closes #341.

Install the environment of a workflow with only a package manager, no ewoks needed:

curl -LsSf https://ewoks.readthedocs.io/en/stable/ewoks-install.sh | sh -s -- demo.json

To try with the current branch:

sh src/ewoks/_bootstrap/ewoks-install.sh demo.json --bootstrap-requirement "-e ."

ewoks-install: create the bootstrap environment /users/denolf/.ewoks/bootstrap/uv/custom=2741135547@python=3.12
ewoks-install: install '-e .' in /users/denolf/.ewoks/bootstrap/uv/custom=2741135547@python=3.12
2026-10-16 17:50:05,002 - /home/denolf/dev/ewoks-kit/ewoks/src/ewoks/_requirements/__init__.py - WARNING  - The requirements do not provide files that the 'uv' package manager can install. The installed python distributions are installed instead.
Distributions:
  networkx==3.7
  pydantic_core==2.50.1
  pillow==12.3.0
  tabulate==0.10.0
  hdf5plugin==7.1.0
  packaging==26.3
  ewokscore==5.0.0
  annotated-types==0.8.0
  silx==3.1.3
  typing-inspection==0.4.4
  h5py==3.16.0
  typing_extensions==4.16.0
  ewoksutils==2.0.0rc2
  pip==26.2.1
  setuptools==84.0.0
  PyYAML==6.0.3
  lxml==6.1.3
  pydantic==2.14.1
  fabio==2026.6.0
  numpy==2.5.4
  filelock==4.2.0
  ewoks==7.0.0rc1
  ewoks==7.0.0rc1

The requirements do not provide files that the uv package manager can install. This will install the python distributions above in a new python environment in '/users/denolf/.ewoks/envs/demo' instead.
Do you want to proceed (y/N)?y
Using CPython 3.12.12
Creating virtual environment at: /users/denolf/.ewoks/envs/demo/.venv
Activate with: source /users/denolf/.ewoks/envs/demo/.venv/bin/activate
2026-10-16 17:50:41,641 - ewoks._requirements.utils.requirements_txt - WARNING  - Skip duplicate requirement 'ewoks==7.0.0rc1'
Using CPython 3.12.12
Resolved 23 packages in 50ms
Installed 22 packages in 43ms
 + annotated-types==0.8.0
 + ewoks==7.0.0rc1 (from git+https://github.com/ewoks-kit/ewoks.git@8ef40bc16aeeccca2fb7f3125e3aaaf83fd386eb)
 + ewokscore==5.0.0
 + ewoksutils==2.0.0rc2
 + fabio==2026.6.0
 + filelock==4.2.0
 + h5py==3.16.0
 + hdf5plugin==7.1.0
 + lxml==6.1.3
 + networkx==3.7
 + numpy==2.5.4
 + packaging==26.3
 + pillow==12.3.0
 + pip==26.2.1
 + pydantic==2.14.1
 + pydantic-core==2.50.1
 + pyyaml==6.0.3
 + setuptools==84.0.0
 + silx==3.1.3
 + tabulate==0.10.0
 + typing-extensions==4.16.0
 + typing-inspection==0.4.4
Bootstrap environment
  Python : /users/denolf/.ewoks/bootstrap/uv/custom=2741135547@python=3.12/bin/python
  Install: /users/denolf/.ewoks/bootstrap/uv/custom=2741135547@python=3.12/bin/python -m ewoks install /users/denolf/dev/ewoks-kit/ewoks/demo.json
  Remove : rm -rf /users/denolf/.ewoks/bootstrap/uv/custom=2741135547@python=3.12
Installed requirements for /users/denolf/dev/ewoks-kit/ewoks/demo.json
  Python : /users/denolf/.ewoks/envs/demo/.venv/bin/python
  Execute: /users/denolf/.ewoks/envs/demo/.venv/bin/python -m ewoks execute /users/denolf/dev/ewoks-kit/ewoks/demo.json
  Remove : rm -rf /users/denolf/.ewoks/envs/demo

What changes

• New bootstrap scripts ewoks-install.sh (Linux/macOS) and ewoks-install.ps1 (Windows, or PowerShell anywhere):
  • Create a cached environment with the ewoks version (and engine) of the workflow.
  • Run ewoks install in it with the remaining arguments.
  • --install-package-manager installs uv, pixi, poetry or conda when missing.
  • --print-command only prints the command.
  • Before the summary of ewoks install, print the bootstrap environment: its python, the command to run ewoks install again and the command to remove it.
  • When the bootstrap fails, print how to install without the script.
• Workflow requirements now also record the ewoks version and the engine that saved the workflow.
• ewoks install prints execute and remove commands that work without ewoks outside the environment (PowerShell syntax on Windows), also with --in-place.
• The documentation serves a demo.json next to the scripts, which the tutorials download to try them without a workflow of your own.

Review guide

1. Python side: requirements metadata and CLI output.
2. The bootstrap scripts, their tests and the CI job tests-package-manager-install (Linux, macOS, Windows).
   • Tests that install package managers from the internet only run with -m package_manager_install.
   • They also run in the nightly CI: https://gitlab.esrf.fr/workflow/external-ci/ewoks-kit/ewoks/-/merge_requests/3
3. Docs.

AI Disclosure

• AI tool Claude used to create the shell scripts, docs and tests.

[woutdenolf]

Print the command to execute ewoks from another terminal.

Edit: done.

[codecov]

Codecov Report

❌ Patch coverage is 54.09836% with 28 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/ewoks/__main__.py	30.76%	27 Missing ⚠️
src/ewoks/_engines.py	87.50%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[woutdenolf]

@loichuder Maybe we should not stick to the oneliner approach?

curl -LsSf https://ewoks.readthedocs.io/en/stable/ewoks-install.sh | sh -s -- demo.json --package-manager-name uv

This does four this:

• download the bootstrap script
• create the bootstrap environment
• run ewoks install in the bootstrap environment (opt-out with the --print-command argument) which create the final enviroment (unless --in-place), ewoks install also prints how the cleanup the environment
• print the pixi run ewoks execute command (or whatever it is)

Especially in terms of arguments this might be confusing. On the other hand for people who do not care and just want it to be done, the oneliner for installation is more convenient.

[loichuder]

Since the oneliner is a convenience thing, I would not go for parametrization.

Either you use the oneliner and you don't have to touch jack. Or you wish to have more control and in this case, you do use the "classical" approach: install ewoks, run ewoks install, etc.