Install & Compatibility
Where this runs
tested against v2.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 2.455s · 166.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 7.5s · import 2.230s · 163MB
160MB installed
● package 160MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Scene
✓ from pythreejs import Scene
PerspectiveCamera
✓ from pythreejs import PerspectiveCamera
WebGLRenderer
✓ from pythreejs import WebGLRenderer
Mesh
✓ from pythreejs import Mesh
BoxGeometry
✓ from pythreejs import BoxGeometry
MeshStandardMaterial
✓ from pythreejs import MeshStandardMaterial
OrbitControls
✓ from pythreejs import OrbitControls
Used for interactive camera control within the renderer.
This quickstart demonstrates how to create a simple 3D scene with a red cube, set up a camera, and render it using `pythreejs` within a Jupyter Notebook or JupyterLab environment. It also includes `OrbitControls` for interactive camera navigation.
from pythreejs import Scene, PerspectiveCamera, WebGLRenderer, Mesh, BoxGeometry, MeshStandardMaterial, OrbitControls
from IPython.display import display
# Create a basic scene with a red cube
scene = Scene(children=[
Mesh(
geometry=BoxGeometry(1, 1, 1),
material=MeshStandardMaterial(color='red')
)
])
# Set up a camera
camera = PerspectiveCamera(position=[3, 3, 3], fov=60, aspect=1.5)
# Create a WebGL renderer and attach the scene and camera
# Add OrbitControls for interactive camera movement
renderer = WebGLRenderer(
scene=scene,
camera=camera,
controls=[OrbitControls(controlling=camera)]
)
renderer.width = 600
renderer.height = 400
# Display the interactive 3D renderer in a Jupyter environment
display(renderer)
Debug
Known issues
gotchapythreejs is a Jupyter widget. It will only render correctly within a Jupyter Notebook or JupyterLab environment. Running code outside of these environments (e.g., in a standard Python script or IDE console) will not display the 3D output.fixEnsure you are running your pythreejs code within a Jupyter Notebook or JupyterLab. For older Jupyter installations, you might need to manually enable the widgetsnbextension (`jupyter nbextension enable --py widgetsnbextension`).
affects: All versions
gotchaPerformance can degrade rapidly with very complex scenes or a large number of objects. While pythreejs leverages the efficient Three.js library, rendering in a browser context through Jupyter still has limitations.fixOptimize your scene: use `BufferGeometry` for custom meshes, merge static meshes where possible, reduce polygon count, and be mindful of the number of active lights and post-processing effects.
affects: All versions
breakingpythreejs closely follows the Three.js API. While it aims to abstract most changes, significant updates in underlying Three.js versions can occasionally lead to changes in how certain properties are set or how objects are constructed.fixAlways consult the pythreejs documentation or examples for your specific version if you encounter unexpected behavior after an update, especially if it relates to object properties or constructor arguments.
affects: Versions where underlying Three.js updates occurred (e.g., 2.0.0 was a major refactor from 1.x).
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pythreejs'
The pythreejs library is not installed in your Python environment.
fixRun `pip install pythreejs` to install the package.
Widget Javascript not detected. Please confirm the Jupyter server is running the widgetsnbextension.
Jupyter's widget extension is not properly enabled or detected by your Jupyter server, which is necessary for interactive widgets like pythreejs to display.
fixTry restarting your Jupyter kernel. If the issue persists, ensure `ipywidgets` is installed (`pip install ipywidgets`) and for older Jupyter versions, you might need to manually enable the extension: `jupyter nbextension enable --py widgetsnbextension --sys-prefix` and `jupyter labextension install @jupyter-widgets/jupyterlab-manager` for JupyterLab.
The 3D canvas appears blank or shows an empty grey box, even after running the code.
Common causes include an incorrectly positioned camera (too far, too close, or pointing away), no light sources in the scene (if using `MeshStandardMaterial`), or objects being outside the camera's view frustum.
fixVerify camera position, target, and `fov`. Ensure there are appropriate light sources (e.g., `DirectionalLight`, `AmbientLight`) in your scene, especially if using materials that react to light. Check object positions relative to the origin and camera.
Upgrade
Version history
2.4.2latest on PyPI · released Feb 20, 2023
Audit
Dependencies
ipywidgetsrequiredCore dependency for Jupyter widget functionality.