Skip to content

Commit 8dc738b

Browse files
authored
Add more IJulia troubleshooting information
1 parent 95f5b9c commit 8dc738b

File tree

1 file changed

+57
-0
lines changed

1 file changed

+57
-0
lines changed

docs/src/providers/ijulia.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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+
4563
Make sure you've installed the `webio_jupyter_extension` package in the same
4664
Python or Conda environment that you're using to launch Jupyter.
4765

@@ -53,6 +71,45 @@ python3 -m pip install webio_jupyter_extension
5371
python3 -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

58115
Open a [GitHub issue](https://github.com/JuliaGizmos/WebIO.jl/issues/new).

0 commit comments

Comments
 (0)