Adapting Debian 12 Linux for MolecularNodes

[aab18011]

Adapting Debian 12 Linux for MolecularNodes: Fixing the Blender Python Interpreter Issue

When setting up the MolecularNodes project on Debian 12 Linux, you might run into a Python-related issue during the Blender and VSCode/VSCodium setup. Specifically, running the build.py script can fail with a ModuleNotFoundError for tomlkit, despite having it installed. This article explains why this happens and how to fix it, especially if you installed Blender via the default Software store.

The Problem

If you installed Blender using the Software store on Debian 12, it’s likely located at /usr/bin/blender and uses the system Python interpreter at /usr/bin/python3.11. This is different from the typical setup where Blender includes its own embedded Python interpreter. When you run:

blender -b -P build.py

You might see an error like this:

ModuleNotFoundError: No module named 'tomlkit'

Even after installing tomlkit with:

/usr/bin/python3.11 -m pip install tomlkit --break-system-packages

The error persists. This happens because Blender’s Python, in this case the system Python 3.11, doesn’t automatically include the user site-packages (e.g., /home/user/.local/lib/python3.11/site-packages) where tomlkit is installed. The Software store installation links Blender to the system Python, creating an unusual configuration that isolates it from user-installed modules.

Running the script with debug lines reveals:

Blender's Python executable: /usr/bin/python3.11
Blender's Python version: 3.11.2 (main, Apr 28 2025, 14:11:48) [GCC 12.2.0]

This confirms Blender is using the system Python, not an embedded one, which explains why it can’t find tomlkit.

The Solution

To make Blender’s Python aware of the user site-packages, you need to modify the build.py script. Add these lines at the top, before any other imports:

import site
import sys
sys.path.append(site.getusersitepackages())

This tells Python to include the user site-packages directory in its module search path. Here’s how the updated build.py should look at the start:

import glob
import os
import subprocess
import sys
from dataclasses import dataclass
from typing import List, Union
import bpy
import site

print("Blender's Python executable:", sys.executable)
print("Blender's Python version:", sys.version)
sys.path.append(site.getusersitepackages())

# Rest of the script follows...

Steps to Apply the Fix

1. Edit build.py:
   Open the script in VSCodium or your preferred editor and add the lines above.
2. Save the File:
   Ensure the changes are saved.
3. Run the Script:
   Execute it again with:

   blender -b -P build.py

   The script should now find tomlkit and run successfully.

Why This Works

The site.getusersitepackages() function returns the path to the user site-packages (e.g., /home/user/.local/lib/python3.11/site-packages), where tomlkit is installed. By appending this to sys.path, Blender’s Python can locate and import the module. This is necessary because the system Python used by Blender, when installed via the Software store, doesn’t include user site-packages by default, unlike a typical embedded Blender Python setup.