No module named 'nbformat' when following macOS VS Code installation instructions

[simonw]

Bug description

I started at https://quarto.org/docs/get-started/ and used the macOS installer to install Quarto. quarto --help confirmed that this had worked.

Then I installed the VS Code extension from https://marketplace.visualstudio.com/items?itemName=quarto.quarto

Everything seemed to work, until I clicked "Render" in VS Code and got this error:

No module named 'nbformat'

I have many different versions of Python 3 installed on my machine. It was not at all obvious to me which one Quarto was using. After some investigation (described here) I figured out it was using this one:

/Applications/Xcode.app/Contents/Developer/usr/bin/python3

So I ran this command to fix my problem:

/Applications/Xcode.app/Contents/Developer/usr/bin/python3 -m pip install nbformat nbclient

After doing that the Render button worked.

Interestingly, the output of quarto check shows /Library/Frameworks/Python.framework/Versions/3.10/bin/python3 as the version of Python - but executing sys.executable in a cell in VS Code showed /Applications/Xcode.app/Contents/Developer/usr/bin/python3 instead. So there's a mismatch between Python versions here.

My operating system is macOS 12.2.1 and I'm running VS Code 1.70.2.

quarto check Output

[✓] Checking Quarto installation......OK
      Version: 1.0.38
      Path: /Applications/quarto/bin

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.10.2
      Path: /Library/Frameworks/Python.framework/Versions/3.10/bin/python3
      Jupyter: 4.11.1
      Kernels: python3

(-) Checking Jupyter engine render....Traceback (most recent call last):
  File "/Applications/quarto/share/jupyter/jupyter.py", line 21, in <module>
    from notebook import notebook_execute, RestartKernel
  File "/Applications/quarto/share/jupyter/notebook.py", line 17, in <module>
    from nbclient import NotebookClient
ModuleNotFoundError: No module named 'nbclient'
There is an unactivated Python environment in jupyter-venv. Did you forget to activate it?

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

quarto tools check Output

~ % quarto tools check
[✓] Inspecting tools

Tool         Status            Installed     Latest  
chromium     Not installed     ---           869685  
tinytex      Up to date        v2022.08      v2022.08

Checklist

• formatted your issue so it is easier for us to read?
• included a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• documented the quarto version you're running, by pasting the output from running quarto check in the "Quarto Check Output" text area?
• documented the version of the quarto tools you're running, by providing the output from running quarto tools check in the "Quarto Tools Check Output" text area?
• documented the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• documented which operating system you're running? If on Linux, please provide the specific distribution as well.
• upgraded to the latest version, including your versions of R, the RStudio IDE, and relevant R packages?

[ryancheley]

I'm seeing this behavior as well.

My operating system is macOS 12.4 and I'm running VS Code 1.70.1.

quarto check Output

[✓] Checking Quarto installation......OK
      Version: 1.0.38
      Path: /Applications/quarto/bin

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.9.10
      Path: /Library/Frameworks/Python.framework/Versions/3.9/bin/python3
      Jupyter: 4.7.1
      Kernels: python3

(/) Checking Jupyter engine render....Traceback (most recent call last):
  File "/Applications/quarto/share/jupyter/jupyter.py", line 21, in <module>
    from notebook import notebook_execute, RestartKernel
  File "/Applications/quarto/share/jupyter/notebook.py", line 16, in <module>
    import nbformat
ModuleNotFoundError: No module named 'nbformat'
There is an unactivated Python environment in venv. Did you forget to activate it?

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

quarto tools check Output

[✓] Inspecting tools

Tool         Status            Installed     Latest  
chromium     Not installed     ---           869685  
tinytex      Not installed     ---           v2022.08

[jjallaire]

The key here is to use the Python: Select Interpreter command in VS Code. This will then make sure that the iPython, Terminal, and Quarto subsystems are all using the same Python.

[simonw]

Thanks for the tip! My VS Code has a LOT of options there, due to the way I use Python (lots of virtual environments) so finding the right one is a bit tricky:

[nickriches]

Thanks @simonw for helping me to sort this. Someone asked a similar question on stackoverflow, and I posted your solution with acknowledgements. Quarto people, this should ideally work out of the box, and seems like an issue which could trip up a lot of users (seemingly a large proportion of Mac users).

[jjallaire]

One problem which occurs frequently is that a newer version of Python gets installed (e.g. via a brew install of some other software) and then VS Code starts defaulting to using that version (which has none of the required packages). So this is a case where the user just shows up one day and Python/Jupyter stops working.

We specifically try to match the version of Python used by default in VS Code so that all Python actions (notebooks, running in the terminal, using Quarto, etc.) use the same version of Python. So while we could "make it work" by hunting around for a version of Python that has the Jupyter packages we'd then be out of sync w/ the rest of VS Code.

I couple things I think we could do:

1. Make a bigger deal out of how to bind Python versions in the VS Code docs (and a warning about "version rot")

2. When we see this particular error, prompt the user explicitly to choose a different version of Python that has Jupyter.