Improve Python detection on windows to support virtualenv activated

[cderv]

Currently on Windows, Quarto detection relies on

• QUARTO_PYTHON being set
• The py.exe launcher being available (with optionally PY_PYTHON being set)
• conda being used

However, in situation where pyenv is used to manage python install, or even uv nowadays, it creates problem. All the more because virtual env is not even taken into account at this step of detection

quarto-cli/src/command/check/check.ts

Lines 335 to 337 in ca05876

	caps = await jupyterCapabilities();
	});
	if (caps) {

cd $env:TEMP
mkdir quarto
cd quarto

uv has some python installed

❯ uv python find
C:\Users\chris\AppData\Roaming\uv\python\cpython-3.13.1-windows-x86_64-none\python.exe

Let's initialize a project with Python 3.13.1

uv init --python 3.13.1
uv add jupyter

Now the version of python for the project is the one from the venv

❯ uv python find
C:\Users\chris\AppData\Local\Temp\quarto\.venv\Scripts\python.exe

But Quarto find none

❯ uv run quarto check jupyter
Quarto 1.7.13
[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

Activating virtualenv puts the python binary on PATH

❯ .\.venv\Scripts\activate
❯ (gcm python).Source
C:\Users\chris\AppData\Local\Temp\quarto\.venv/Scripts\python.exe

But still quarto can't find it

❯ quarto check jupyter
Quarto 99.9.9
[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

This is because

• VIRTUAL_ENV env var is not check at detection step but later for kernel spec information
• windows has python.exe on PATH and not python3.exe and dectection code does not account for that.

If py.exe was available then it would work.

❯ cd C:\Users\chris\AppData\Local\Temp\quarto
❯ py -0
No installed Pythons found!
❯ .\.venv\Scripts\activate
❯ py -0
  *               Active venv
❯ quarto check jupyter
Quarto 99.9.9
[>] Checking Python 3 installation....OK
      Version: 3.13.1
      Path: C:/Users/chris/AppData/Local/Temp/quarto/.venv/Scripts/python.exe
      Jupyter: 5.7.2
      Kernels: python3, julia-1.11

[>] Checking Jupyter engine render....OK

So current situation on windows does rely too much on py.exe which is only available for user using Windows Store Python version, or installing from the Python official website.

Related to

• Support other python on Windows than py.exe supported ones (like pyenv) #1463

[westat-schneider]

I also experience this issue when trying to run Quarto on Windows for projects where the virtual environment was created using uv, which basically prevents folks at my Windows-heavy organization from using Quarto and uv together.

[cderv]

which basically prevents folks at my Windows-heavy organization from using Quarto and uv together

This kind of issue is never a blocker as QUARTO_PYTHON can be set to a specific python version and avoid detection. For example $env:QUARTO_PYTHON=$(uv python find)

Then the issue I mentioned is about quarto check reporting the wrong version.

For rendering, there is not issue as long as you activate the virtual environment first - which is what we recommend not only on windows: https://quarto.org/docs/projects/virtual-environments.html#using-venv

So on windows using uv, from your project root, you can do

> .\.venv\Scripts\activate
> quarto render

(but quarto check jupyter still find not python)

You can also leverage uv run directly, as the command will be ran in the virtual env

uv run quarto render

So I would lower you assertiation about basically preventing folks on Windows to currently use Quarto with uv and Python.

I may be missing some use cases here, so feel free to add some more example that are really blocker.

We'll fix the quarto check jupyter for sure, so it does not feel like a blocker. Real problem is that currently it relies a lot on py.exe launcher - and it happens it is now less generalized on windows as before since uv is out. 😅

[westat-schneider]

Thanks, the suggestion to wrap quarto render inside uv run works here and seems like the cleanest option.

You can also leverage uv run directly, as the command will be ran in the virtual env

Maybe content about uv could be added to the Quarto docs on virtual environments?

https://quarto.org/docs/projects/virtual-environments.html