@@ -42,6 +42,24 @@ python3 -m pip uninstall webio_jupyter_extension
4242
4343### The ` webio_jupyter_extension ` is installed but not working
4444
45+ First, check if the WebIO extension is properly installed:
46+ ```
47+ # For classic notebook
48+ jupyter nbextension list
49+ # Should include in output:
50+ # notebook section
51+ # webio-jupyter-nbextension/nbextension enabled
52+
53+ # For Jupyter lab
54+ jupyter labextension list
55+ # Should include in output:
56+ # webio-jupyterlab-provider vX.Y.Z enabled OK (python, webio_jupyter_extension)
57+ ```
58+
59+ If the installation is ** NOT** installed, continue reading for troubleshooting steps.
60+
61+ #### 1: Make sure to use same Python/Conda environment for both Jupyter and WebIO
62+
4563Make sure you've installed the ` webio_jupyter_extension ` package in the same
4664Python or Conda environment that you're using to launch Jupyter.
4765
@@ -53,6 +71,45 @@ python3 -m pip install webio_jupyter_extension
5371python3 -m jupyterlab
5472```
5573
74+ #### 2: Make sure to be consistent with ` --user ` pip installations
75+ The WebIO extension will not be detected if Jupyter is intalled system-wide and
76+ the WebIO extension is installed in your user installation (or vice-versa). Pip
77+ might install into the per-user install directory if you use the ` --user ` flag OR
78+ if you don't have permission to edit the global installation.pip
79+
80+ You can determine if this is the case by inspecting where the packages are installed:
81+ ``` sh
82+ # replace "jupyterlab" with "notebook" for classic notebook
83+ pip3 show jupyterlab | grep -i location
84+ pip3 show webio_jupyter_extension | grep -i location
85+ ```
86+
87+ If this happens, the easiest solution is to uninstall and reinstall all relevant:
88+ ```
89+ pip3 uninstall jupyter notebook jupyterlab webio_jupyter_extension
90+
91+ # If you want to install it on a per-user basis, omit the "sudo" and change
92+ # "install" to "install --user"
93+ sudo pip3 install jupyter notebook jupyterlab webio_jupyter_extension
94+ ```
95+
96+ ** Alternatively:** This problem can be avoided using virtual environments:
97+ ```
98+ # Create a new virtual environment (you only have to do this once!)
99+ python3 -m venv venv
100+
101+ # Activate the virtual environment
102+ . venv/bin/active
103+
104+ # Install Jupyter + WebIO extension (you only have to do this once!)
105+ pip install notebook jupyterlab webio_jupyter_extension
106+
107+ # Launch jupyter
108+ jupyter lab # or jupyter notebook
109+ ```
110+ If using virtual environments, you must always start Jupyter using a virtual
111+ environment that has the WebIO extension installed.
112+
56113## Still having problems?
57114
58115Open a [ GitHub issue] ( https://github.com/JuliaGizmos/WebIO.jl/issues/new ) .
0 commit comments