Project Scaffolding

[vacquah]

I am new to observable notebooks in general and have a few questions about the right way to configure a project. I got started by installing notebook-kit with:

cd workshop/observable-notebooks/test-notebook
--
npm init -y
npm add @observablehq/notebook-kit
npm add postgres
npm add @duckdb/node-api

Now, I see in the dataloaders documentation, mention of python environments? My current 2.0 notebook cell does not have python as an option.

Do I need to setup a python virtual environment for my notebook projects? A bit confused. I am on the latest version 1..3.0

[mbostock]

Database connectors (SQL cells) and data loaders (Node.js and Python cells) are both optional features. Note that while Observable Notebook Kit 1.3.0 with support for data loaders has been released, Observable Desktop 1.3.0 has not been released yet — that will likely happen later today or tomorrow. (And you’ll either need to download it, or restart Desktop a couple times to get the automatic update.)

If you’re using database connectors with Observable Notebook Kit, you must install database drivers (as you said you have done). You do not need to install database drivers if you are using Observable Desktop (our macOS desktop application), as they come installed.

If you want to use data loaders, you must install the corresponding interpreter (Node.js or Python). These interpreters do not come bundled with Observable Notebook Kit or Observable Desktop. I recommend using Homebrew on macOS, but there are also official installers for Node.js and Python.

If you are using Python data loaders, you can use a virtual environment if you want, but it is not required. To create a Python virtual environment, you can first cd to the directory containing your notebooks, and then run something like this:

python3 -m venv .venv
source .venv/bin/activate
pip install numpy pandas
pip freeze > requirements.txt

If you do this, Observable Desktop and Observable Notebook Kit will automatically use your virtual environment. If you don’t setup a virtual environment, then your global Python installation will be used instead.

[vacquah]

@mbostock I usually use uv to provision my virtual environments, so in this case:

• cd /test-notebook
• uv venv
• source .venv/bin/activate
• install any dependancies e.g uv add pandas numpy

This is where I get a bit fuzzy. Since I am using the desktop too I guess I don't need to do any of this :

• npm init -y
• npm add postgres
• npm add @duckdb/node-api

But to use notebook kit I will need to do this in the same directory?

• npm init -y
• npm add @observablehq/notebook-kit

I do have node.js and python available on my mac. I will wait to update the desktop app whenever its available. gracias.

[mbostock]

I haven’t tested uv yet, so I’m not sure if that will work… I’ll try and report back. (If uv creates a .venv/bin/python3, then it should “just work.”)

I should also clarify that if you are using Notebook Kit, it will use python3 or node on your $PATH environment variable rather than searching in specific locations as Desktop does. This means you need to run Notebook Kit within your virtual environment (using source .venv/bin/activate before running Notebook Kit). It is only Desktop that does not have access to $PATH and therefore searches for python3 in the common locations, including within .venv.

If you are using Desktop, you don’t need npm, or to install Notebook Kit or database drivers. But you do need to install Node.js or Python, if you want those.

[mbostock]

Confirmed that uv (uv venv) works as intended. ✅

[vacquah]

Yes, working on my end too. gracias. need to figure out when to use notebook-kit and when to use desktop, but I have a working dev space now I can play with, in a python virtual env.