Quarto fails to recognize Python virtual environment

[aronvandepol]

Description

I have recently switched to astral UV to manage python for me. I have tried to make it work nicely with Quarto and setup a testing script to do this. I create a virtual env with UV that my quarto project will use. this is located at .venv dir next to the quarto qmd file.

I manually install jupyter using uv pip install jupyter to ensure the venv can work with quarto.

I have tried the following configs to make quarto pick this up:

1. (Set executable)

---
title: "Testing UV with Quarto"
execute:
  python: ".venv/bin/python"
  external: true

---

## Testing Pandas with UV

```{python} 
#| echo: false
#| code-fold: true
!uv pip install pandas torch
```


```{python}
import pandas as pd

# Create a sample DataFrame
data = pd.DataFrame({
    "Name": ["Alice", "Bob", "Charlie", "David"],
    "Age": [24, 27, 22, 32],
    "City": ["New York", "Los Angeles", "Chicago", "Houston"]
})

# Display the DataFrame
print("Sample DataFrame:")
print(data)
```

```{python} 
import torch
x = torch.rand(3,3)
print(x)
```

quarto render results in a 'There is an unactivated Python environment in .venv. Did you forget to activate it?' error. Alongside the fact that the packages weren't installed.

I then adjusted the _quarto.yml

project:
  type: website
  pre-render:
  - "./set.sh"

this calls the prerender script:

export QUARTO_PYTHON=.venv/bin/python

calling quarto render with this still results in it not using the environment.

I then came across the _environtment file which i tried to setup.

_environment

QUARTO_PYTHON=.venv/bin/python

Again, we get the same error that the python venv is not being used.

When in my terminal I source the venv directly using source ./venv/bin/activate and run quarto render still the same error occurs.

Only when i call" export QUARTO_PYTHON=.venv/bin/python directly before running quarto render will the test file run. The necessary packages get installed first through !uv pip install pandas torch and the code and renders into a html file without errors.

My question is if there is a different way, preferably through Quarto, either the project _quarto.yml or the _environment file to set this? Perhaps I am doing something wrong? The idea is that I don't have to call export QUARTO_PYTHON=.venv/bin/python in my terminal everytime before rendering.

Any help is appreciated!

[mkdjr]

Thanks for your post! I just got my setup working so I'll share what I did and maybe that will work for others!

View the kernels registered with jupyter: uvx jupyter kernelspec list. You should see something like this (angle brackets indicate information that will be specific to your setup):

Available kernels:
  <kernel_name>   <kernel_directory_path>

View the content of the kernel configuration file: cat <kernel_path>/kernel.json:

   1   │ {
   2   │  "argv": [
   3   │   <kernel_python_executable_path>,
   4   │   "-Xfrozen_modules=off",
   5   │   "-m",
   6   │   "ipykernel_launcher",
   7   │   "-f",
   8   │   "{connection_file}"
   9   │  ],
  10   │  "display_name": <kernel_name>,
  11   │  "language": "python",
  12   │  "metadata": {
  13   │   "debugger": true
  14   │  }
  15   │ }

I then created an _environment.yml file in the root of my quarto project directory that sets PYTHON_PATH=<kernel_python_executable_path>.

I think the reason it wasn't working for me previously was because I had configured quarto to look at a different python path than what the kernel was using. I also made sure to specify which kernel I wanted the document code to be executed with:

---
jupyter: <kernel-name>
---

[cderv]

I am surprised this needs to be done, but I think this is because your are using a global jupyter install using uvx jupyter.

Using _environment.yml is definitely a good way to set an env var for the project.Though, quarto respect QUARTO_PYTHON to bypass auto detection, and not PYTHON_PATH - so maybe this is not for quarto directly you do this ?

Specifying a kernel is great to avoid error, but could cause reproducibility issue or collaboration issue. We need to make this available at project level probably 🤔

[cderv]

@aronvandepol where did you find mention of this ?

execute:
  python: ".venv/bin/python"
  external: true

I am not sure this is supposed to work... 🤔

calling quarto render with this still results in it not using the environment.

pre-render script is not meant to set some state for the rendering. This won't be the same process. So you can't set env var this way. See about https://quarto.org/docs/projects/environment.html for project

This is how you should be able to configure a QUARTO_PYTHON for your project.

When in my terminal I source the venv directly using source ./venv/bin/activate and run quarto render still the same error occurs.

However, this should work; If you activate the venv before running quarto render, the right python version should be used. We described this in https://quarto.org/docs/projects/virtual-environments.html#using-venv

We do this in our own CI workflow for testing. Activate the environment, then call quarto render. Possibly for uv managed project uv run is also an option: https://docs.astral.sh/uv/concepts/projects/run/

[aronvandepol]

@aronvandepol where did you find mention of this ?

execute:
python: ".venv/bin/python"
external: true

I am not sure this is supposed to work... 🤔

I tried my best to backtrack where I got this idea/suggestion but could not find it, Sorry. See it as an error and misunderstanding on my part.

I think your suggestion of adding it in the CI workflow makes sense. Adding it to load before build seems sensible and would work when I rebuild on my server. I will certainly implement this.

While not a big deal on its own, I don't call a build script to preview or render my site locally, but do source my venv. So I'm confused why it didn't catch it automatically as indeed described in the docs you mentioned. I will do some more testing to see if I can replicate this behavior as its been since October that I tried to make it work the last time.

I will also give @mkdjr suggestion a try soon see how that works. But seeing your comment there perhaps the best workflow here is indeed locally sourcing your venv (again assuming that this should work) and on the server side when building have it source it through a build script.

Thanks for your reply and will update the thread here with findings.

[dmi3kno]

Could we also make sure that quarto check detects the local uv environment? It would be nice to be able to auto-activate the environment on running the quarto render or quarto preview in the directory where the uv environment is present

[dmi3kno]

Thank you very much for this clarification!

[aronvandepol]

i have tried to follow these instructions with the export but keep running into the issue of it reverting to a different python version then I export.

test on  main [?] is 󰏗 v0.1.0 via  v3.12.6 (test) took 4s
❯ ls
main.py  pyproject.toml  README.md  uv.lock

test on  main [?] is 󰏗 v0.1.0 via  v3.12.6 (test)
❯ source activate ./.venv/bin/activate

test on  main [?] is 󰏗 v0.1.0 via  v3.12.6 (test)
❯ export QUARTO_PYTHON="./.venv/bin/python3.12"

test on  main [?] is 󰏗 v0.1.0 via  v3.12.6 (test)
❯ uv run quarto check jupyter
Quarto 1.7.30
[✓] Checking Python 3 installation....OK
      Version: 3.12.10
      Path: /nix/store/h6sfgyh9h3q7q2y5777ndljhcj1klqgp-python3-3.12.10-env/bin/python3.12
      Jupyter: 5.7.2
      Kernels: python3

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

any qmd file that loads any package installed (e.g. matplotlib) fails to load because it doesn’t actually move towards the .venv and returns me with:

ModuleNotFoundError: No module named 'matplotlib'

There is an unactivated Python environment in .venv. Did you forget to activate it?

I run through uv run quarto render and have exported as follows: export QUARTO_PYTHON="./.venv/bin/python3.12"

i have also attempted export QUARTO_PYTHON="./.venv/bin/jupyter" which also had no effect.

[mcanouil]

@aronvandepol unfortunately you are using a version of Quarto CLI not officially packaged that uses untested dependencies (NixOS). Absolutely no guarantees can be provided of Quarto CLI working as designed.

[aronvandepol]

I can confirm that there seems to have been an issue with the nix version. Installing via brew solved these issues.

[cderv]

From what I know about Nix and their packaging (though very little), they probably override the QUARTO_PYTHON environment variable to make their bundling work. So you may not be able to use virtual environment - you need to use the environment associated with the installed version I guess.

See for example https://github.com/NixOS/nixpkgs/blob/910796cabe436259a29a72e8d3f5e180fc6dfacc/pkgs/development/libraries/quarto/default.nix#L67

This seems to be configurable, but you need to find documentation for this Nix package

Also see this past discussion from a Nix user

• how to set the python kernel for quarto in Nix context #12506

[kodonian]

I’m trying to use virtual Python environments created with uv for my Quarto projects to ensure reproducibility and isolated dependencies. Activating the environment works in the current terminal session, but as soon as I reopen a terminal for package installation the activation is lost.

I’ve seen earlier discussions around Python kernel selection and the QUARTO_PYTHON environment variable (e.g. #12506, #11804), but none seem to provide a seamless solution across multiple Quarto projects.

Since I’m working with several Quarto projects in parallel, each using its own .venv, I’d like a project-local way to configure which Python environment should be used — ideally without requiring global kernel installation or modifying shared paths.

I tried globally unsetting QUARTO_PROJECT and using a local _environment file to set QUARTO_PYTHON per project, but that doesn’t seem to be interpreted at all. Kernel configuration via ipykernel works, but introduces overhead and breaks portability due to hardcoded paths.

What do you think about an execute setting in _quarto.yml that allows to specify the project's Python path?

[kodonian]

interesting, will look into it. I am using Positron, maybe I can copy the settings. Thanks!

[cderv]

I am using Positron

Positron should discover UV environment, and use this: https://positron.posit.co/python-installations.html
Can you check this is the case ?

Maybe Quarto VSCODE extension is not correctly using the same version in Positron. I think it should. 🤔

[mcanouil]

Few settings, you might want to check:

• python-envs.defaultEnvManager default to use venv ms-python.python:venv
• python.defaultInterpreterPath check that it's not set globally

As Positron is based on the open source code from VSCode, most of the VSCode documentation should apply, thus I suggest to read how environments work there: https://code.visualstudio.com/docs/python/environments

[kodonian]

Thanks, guys! I think I’ve found the culprit.

I wasn’t aware that Positron/VSCode auto-detects virtual environments.

My project is structured with all project files in a main folder and Quarto-specific files in a /quarto subdirectory. Initially, I had created the virtual environment inside /quarto/.venv. However, since Positron doesn’t recognize that location as a valid virtual environment root, it didn’t automatically set the QUARTO_PYTHON environment variable for terminal sessions.

I’ve now moved the .venv folder one level up to — to the project root — and everything works out of the box 🙏

[mcanouil]

VSCode/Positron has a setting to change the location of this folder if that helps.