Skip to content

Setting up a Jupyter Notebook Environment with PythonSCAD on Linux

This guide explains how to set up a clean Jupyter Notebook environment for PythonSCAD on Linux, starting from a fresh Conda installation.

1. Install Miniconda

Download the latest Miniconda installer:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

Run the installer:

bash Miniconda3-latest-Linux-x86_64.sh

Accept the defaults and allow Conda to initialize your shell.

Restart your terminal and verify installation:

conda --version

2. Create a Dedicated Environment

Create a clean environment for PythonSCAD:

conda create -n pythonscad python=3.11

Activate it:

conda activate pythonscad

3. Install Required Packages

Install core dependencies:

conda install numpy cmake
pip install notebook ipywidgets pythreejs ipykernel

If using classic Jupyter Notebook (v6), enable widgets:

jupyter nbextension enable --py widgetsnbextension --sys-prefix

For Notebook 7 or JupyterLab, widgets work automatically.

4. Install PythonSCAD

Navigate to your PythonSCAD project directory:

cd ~/git/pythonscad

Install in editable (development) mode:

pip install -e .

Verify installation:

python -c "import pythonscad; print(pythonscad.__file__)"

5. Register the Kernel with Jupyter

Make the Conda environment available in Jupyter:

python -m ipykernel install --user --name pythonscad --display-name "PythonSCAD"

Start Jupyter:

jupyter notebook

Select the PythonSCAD kernel in the Notebook interface.

6. Test 3D Rendering

In a notebook cell:

import pythonscad as ps

obj = ps.cube([10, 10, 10])
obj

If correctly configured:

  • The object renders as a 3D widget
  • ipywidgets display properly
  • No comm protocol errors appear

7. Development Workflow

If you modify C++ sources:

cmake --build build

Restart the Jupyter kernel after rebuilding.

Because PythonSCAD is installed in editable mode, no reinstall is necessary.

8. Troubleshooting

Widgets appear as text (e.g. IntSlider(value=0))

Check:

jupyter nbextension list

If disabled:

jupyter nbextension enable --py widgetsnbextension --sys-prefix

Wrong Python environment

Verify:

which python
which jupyter

Both must point inside:

miniconda3/envs/pythonscad/

Inside a notebook:

import sys
print(sys.executable)

pythonscad/
├── pyproject.toml
├── CMakeLists.txt
└── src/
    └── pythonscad/
        ├── __init__.py
        ├── jupyterdisplay.py
        └── _core.so

This ensures clean imports like:

import pythonscad.jupyterdisplay

Done

You now have:

  • An isolated Conda environment
  • Jupyter Notebook
  • ipywidgets and pythreejs
  • PythonSCAD installed in development mode
  • Working 3D rendering support