|
1 | 1 | # Troubleshooting guide for MATLAB Integration _for Jupyter_ |
2 | | -We have provided a Python script, troubleshooting.py, which runs basic environment checks to determine if the required dependencies are met or not. This script does not send the information anywhere remotely and just relays information to the terminal window. |
| 2 | + |
| 3 | +This folder contains `troubleshooting.py`, a Python script that checks your environment for the dependencies required to run [MATLAB Integration for Jupyter](https://github.com/mathworks/jupyter-matlab-proxy/tree/main). The script prints the results in your terminal. |
3 | 4 |
|
4 | 5 |
|
5 | 6 | ## Table of Contents |
6 | 7 | 1. [Requirements](#requirements) |
7 | | -2. [Running the script](#running-the-script) |
| 8 | +2. [Run Troubleshooting Script](#run-troubleshooting-script) |
8 | 9 | 3. [Enable Logging](#enable-logging) |
9 | 10 |
|
10 | 11 | ## Requirements |
11 | | -* Python |
12 | | - |
13 | | -## Running the script |
14 | | -One can run the latest version of the troubleshooting script using the following command: |
15 | | - |
16 | | -```bash |
17 | | -$ curl https://raw.githubusercontent.com/mathworks/jupyter-matlab-proxy/main/troubleshooting/troubleshooting.py | python - |
18 | | -``` |
| 12 | +- Python |
19 | 13 |
|
20 | | -Ensure that the `python` executable used to run this script is from the same environment in which you intend to use the integration. |
| 14 | +## Run Troubleshooting Script |
21 | 15 |
|
22 | | -Also, if you are on a platform that doesn't support `curl`, please consider downloading the [troubleshooting.py](https://raw.githubusercontent.com/mathworks/jupyter-matlab-proxy/main/troubleshooting/troubleshooting.py) and running it as: |
| 16 | +Ensure the Python executable you use to run the troubleshooting script is in the same environment where you want to use the integration. |
23 | 17 |
|
24 | | -```bash |
25 | | -$ python troubleshooting.py |
26 | | -``` |
| 18 | +Run the troubleshooting script: |
27 | 19 |
|
28 | | -Alternatively, you can manually execute the below commands in the environment where you have installed the package: |
29 | | - |
30 | | -* Verify that the MATLAB executable is on the PATH |
31 | 20 | ```bash |
32 | | -$ which matlab |
33 | | -/usr/local/bin/matlab |
34 | | -``` |
35 | | - |
36 | | -* Check if the Python version is 3.8 or higher |
37 | | -```bash |
38 | | -$ python --version |
39 | | -Python 3.8.3 |
40 | | -``` |
41 | | - |
42 | | -* Ensure that `matlab-proxy-app` and the `jupyter` executables are in the same environment as the Python executable. |
43 | | -For example, if you are using VENV to manage your Python environments: |
44 | | -```bash |
45 | | -$ which python |
46 | | -/home/user/my-project/packages/.venv/bin/python |
47 | | - |
48 | | -$ which matlab-proxy-app |
49 | | -/home/user/my-project/packages/.venv/bin/matlab-proxy-app |
50 | | - |
51 | | -$ which jupyter |
52 | | -/home/user/my-project/packages/.venv/bin/jupyter |
| 21 | +$ curl https://raw.githubusercontent.com/mathworks/jupyter-matlab-proxy/main/troubleshooting/troubleshooting.py | python - |
53 | 22 | ``` |
54 | | -Notice that `matlab-proxy-app`, `jupyter` and the `python` executable are in the same parent directory, in this case, it is: `/home/user/my-project/packages/.venv/bin` |
55 | 23 |
|
56 | | -* Ensure that you are launching `jupyter lab` using the same executable listed above. |
| 24 | +If your platform does not support `curl`, download [troubleshooting.py](https://raw.githubusercontent.com/mathworks/jupyter-matlab-proxy/main/troubleshooting/troubleshooting.py) and run it: |
57 | 25 |
|
58 | | -* Ensure that all three packages are installed in the same Python environment |
59 | 26 | ```bash |
60 | | -# Pipe the output of pip freeze and grep for jupyter, matlab-proxy and jupyter-matlab-proxy. |
61 | | -# All three packages should be highlighted in the output. |
62 | | -# If you don't see any one of them, then either the packages missing in the output have been installed |
63 | | -# in a different Python environment or not installed at all. |
64 | | -$ pip freeze | grep -E "jupyter|matlab-proxy|jupyter-matlab-proxy" |
65 | | -``` |
66 | | - |
67 | | -* If the integration is not a visible option in the dropdown box inside the Jupyter Notebook: |
68 | | -```bash |
69 | | -#Run the following commands and verify that you are able to see similar output: |
70 | | - |
71 | | -$ jupyter serverextension list |
72 | | -config dir: /home/user/anaconda3/etc/jupyter |
73 | | -jupyter_server_proxy enabled |
74 | | -- Validating... |
75 | | -jupyter_server_proxy OK |
76 | | -jupyterlab enabled |
77 | | -- Validating... |
78 | | -jupyterlab 3.5.1 OK |
79 | | - |
80 | | -$ jupyter nbextension list |
81 | | -Known nbextensions: |
82 | | -config dir: /home/user/anaconda3/etc/jupyter/nbconfig |
83 | | -notebook section |
84 | | -jupyter-js-widgets/extension enabled |
85 | | -- Validating: OK |
86 | | -tree section |
87 | | -jupyter_server_proxy/tree enabled |
88 | | -- Validating: OK $ pip freeze | grep -E "jupyter|matlab-proxy|jupyter-matlab-proxy" |
89 | | - |
90 | | -$ jupyter labextension list |
91 | | -jupyterlab_pygments v0.2.2 enabled OK (python, jupyterlab_pygments) |
92 | | -jupyter_matlab_labextension v0.1.0 enabled OK |
93 | | -@jupyterlab/server-proxy v3.2.2 enabled OK |
94 | | - |
95 | | - |
96 | | -# IF the server does not show up in the commands above, install: |
97 | | -$ pip install jupyter-contrib-nbextensions |
| 27 | +$ python troubleshooting.py |
98 | 28 | ``` |
99 | 29 |
|
100 | 30 | ## Enable Logging |
101 | 31 |
|
102 | | -You can use logs to assist debugging while using MATLAB Integration for Jupyter. Set the environment variable `MWI_JUPYTER_LOG_LEVEL` to one of the following: `NOTSET`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `CRITICAL`. The default value is `INFO`. For more information on Python log levels, see [Logging Levels](https://docs.python.org/3/library/logging.html#logging-levels). |
| 32 | +You can use logs to assist debugging when using MATLAB Integration for Jupyter. Set the environment variable `MWI_JUPYTER_LOG_LEVEL` to one of the following: `NOTSET`, `DEBUG`, `INFO`, `WARN`, `ERROR`, or `CRITICAL`. The default value is `INFO`. For more information on Python log levels, see [Logging Levels (Python)](https://docs.python.org/3/library/logging.html#logging-levels). |
103 | 33 |
|
104 | 34 | To set the environment variable, use the appropriate command for your environment. For example, in Linux, use the following: |
105 | 35 |
|
|
0 commit comments