🧑‍💻 Add uv setup workflow

[abdol]

Implements #1056.

Description

The developers of ruff has also made uv, a package manager that claims to be at least 10x times faster than pip. It can also setup a virtual python environment and install dependencies in one go.

I'm considering having a go at adding a uv-based development setup for TIAToolbox.

An example workflow will be:

git clone https://github.com/TissueImageAnalytics/tiatoolbox.git
cd tiatoolbox
uv sync
.venv\Scripts\activate.bat # win32
source .venv/bin/activate # (mac/Linux)

After that, the dependencies will installed in a new Python venv environment.

Reviewing

Can you try testing if the workflow works on Windows and Linux, with and without GPU?

How to Test

Please refer to the branch's README for installation steps.

We need to verify that the PR works across:

• macOS
• Windows (cuda)
• Linux (cuda)

Feedback is appreciated. Thanks!

TODO

• Develop uv implementation
• Update PR description to include a introduction to the change and how to use it
• Add instructions on how to install uv on Windows
• Remove conda .yml files (and its reference in conda-env-create.yml)
• Add uv install instruction for stable version (not only develop)
• Pin python version
• Check uv installation for mps
• Investigate replacing poetry with uv

[shaneahmed]

Thanks @abdol for creating this PR. We would like to have uv support so that's a good start. However, there are a few comments:

1. We should not have duplication of requirements file and pyproject.toml. We should have all the dependencies listed in one file.
2. We should not replace conda in README at least for now.
3. Can you remove uv.lock as it is probably not required to be on the repo.
4. Probably add uv installation instructions to https://tia-toolbox.readthedocs.io/en/latest/installation.html

[abdol]

• We should not have duplication of requirements file and pyproject.toml. We should have all the dependencies listed in one file.

@shaneahmed do you have a preference, i.e., requirement file or pyproject.toml?

[shaneahmed]

• We should not have duplication of requirements file and pyproject.toml. We should have all the dependencies listed in one file.

@shaneahmed do you have a preference, i.e., requirement file or pyproject.toml?

pyproject.toml is better.

[abdol]

@shaneahmed I have addressed your feedback as follows:

1. All requirements are now unified in pyproject.toml (this needs thorough testing as it affects installing using conda as well)
2. Removed uv.lock (and added it to .gitignore)
3. Added uv installation guide to readthedocs

Regarding the following point:

• We should not replace conda in README at least for now.

Do you mean that conda should remain as the recommended installation method? Thanks

[shaneahmed]

Thanks @abdol . I have added some comments. Install works fine on Linux but not on Windows.

[abdol]

But then there is an error

  × Failed to build `stringzilla==4.6.1`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `build_backend.build_wheel` failed (exit code: 1)

      [stdout]
      running bdist_wheel
      running build
      running build_py
      creating build\lib.win-amd64-cpython-314\cli
      copying cli\split.py -> build\lib.win-amd64-cpython-314\cli
      copying cli\wc.py -> build\lib.win-amd64-cpython-314\cli
      copying cli\__init__.py -> build\lib.win-amd64-cpython-314\cli
      running build_ext
      building 'stringzilla' extension

      [stderr]
      error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/```

Thanks for reporting this issue @shaneahmed. Can you confirm whether this issue occurs when you run uv sync?

[shaneahmed]

But then there is an error

  × Failed to build `stringzilla==4.6.1`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `build_backend.build_wheel` failed (exit code: 1)

      [stdout]
      running bdist_wheel
      running build
      running build_py
      creating build\lib.win-amd64-cpython-314\cli
      copying cli\split.py -> build\lib.win-amd64-cpython-314\cli
      copying cli\wc.py -> build\lib.win-amd64-cpython-314\cli
      copying cli\__init__.py -> build\lib.win-amd64-cpython-314\cli
      running build_ext
      building 'stringzilla' extension

      [stderr]
      error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/```

Thanks for reporting this issue @shaneahmed. Can you confirm whether this issue occurs when you run uv sync?

Yes

[shaneahmed]

git clone https://github.com/TissueImageAnalytics/tiatoolbox.git

uv python pin 3.12
uv venv --python 3.12

could help!

[shaneahmed]

git clone https://github.com/TissueImageAnalytics/tiatoolbox.git

uv python pin 3.12
uv venv --python 3.12

could help!

uv sync works fine on windows with python 3.12 and python 3.13. Python 3.14 is now supported by stringzilla version 4.6.2 https://github.com/ashvardanian/StringZilla/releases/tag/v4.6.2.

On Windows there is also an issue of installation of OpenJpeg which needs to be resolved. The other option is we use conda to create the environment, install openjpeg using conda install -c conda-forge openjpeg and use uv pip install .[dev]

[abdol]

@shaneahmed can you try to install again on Windows with Python 3.14? I have pushed an experimental fix that makes sure that README and HISTORY.md are read with UTF-8 in setup.py:

    with Path("HISTORY.md").open(encoding="utf-8") as history_file:
...

I suspect that the issue stems from the emojis used in HISTORY.md.

[abdol]

The PR is now ready for final review. If Windows install works okay, I think we can proceed with merging. Thanks!

[shaneahmed]

Thanks @abdol. I am able to install it, however since the install requires openjpeg and sqlite installation on Windows via conda. I would prefer to keep that in the main README.md to avoid any confusion. We can keep uv installation instructions in the Installation doc.

In this file, let's keep it simple and stick to conda environments only. We also need to add the following to instructions.

conda install -c conda-forge openjpeg sqlite

The rest of the PR looks good.

[abdol]

Thanks @shaneahmed, will do. Regarding the last point:

We also need to add the following to instructions.

conda install -c conda-forge openjpeg sqlite

Do you mean adding the above line to the uv or conda installation instructions? Thank you

[shaneahmed]

Please add above line to both installation instructions as these are required anyway. Actually, you do not need to add conda install -c conda-forge openjpeg sqlite in installation.rst. It is in Pre-Requisites at the top anyway.

Please add it to README.md and only provide conda instructions in README.md file.

[abdol]

Thanks @shaneahmed, this is done now in the following commits:

• 453e34b removed uv install instructions from README
• 6917779 added a conda install -c conda-forge openjpeg sqlite to README.

Please let me know if I have missed anything.