Connect to a JupyterHub from Visual Studio Code
Visual Studio Code has pretty good support
for running Jupyter Notebooks. But what if your organization has a JupyterHub running remotely, with more compute resources & access to large amounts of data? How can you access that from Visual Studio Code running on your local machine?
It’s pretty easy to do, and this blog post will guide you through it.
Step 1: Get a JupyterHub access token
JupyterHub lets you create tokens for yourself for use by third party applications. These tokens can be used anywhere a Jupyter Notebook access token is needed. Since this is what Visual Studio Code needs, let’s acquire one.
- Log-in to your JupyterHub
- Access your Control Panel. In classic notebook, there is a ‘Control Panel’ button on the top right. In JupyterLab, you can access it under ‘File -> Hub Control Panel’
3. Go to the ‘Token’ page by clicking ‘Token’ in the top bar
4. Type in a description for the new token you want, and click ‘Request new API Token’
5. Copy your token and keep it somewhere safe. You should treat this like a password to your JupyterHub. You can (and should!) revoke it (as I have done) from the same page when you are no longer using it.
This is all the information you need from JupyterHub! Now let’s go to vscode.
Step 2: Connect VS Code to your JupyterHub
Visual Studio Code supports connecting to a remote notebook server, and we can use that to connect to our JupyterHub. You must perform these steps before opening your notebook.
- Open the command palette in Visual Studio Code (‘Cmd+Shift+P’ on MacOS, ‘Ctrl+Shift+P’ elsewhere)
- Select ‘Python: Specify local or remote Jupyter server for connections’
3. Construct your notebook server URL with the following template: https://<your-hub-url>/user/<your-hub-user-name>/?token=<your-token>. Note that your hub user name might sometimes be escaped from whatever you used to actually log in, if it has special characters. You can verify this by looking at the URL you get once you log in to your JupyterHub — it should have the right one after ‘user’.
4. Create or open a new notebook. The kernel for this should now live on your JupyterHub! You can verify this by running !hostname, which should return the hostname of your remote JupyterHub server instead of your local hostname. You can also try importing libraries that are in the remote JupyterHub server, but not your local file system.
Tada! That wasn’t so hard, was it?
Limitations
- Your JupyterHub notebook server must be running already when you try to open your notebook — Visual Studio Code will not automatically start it. If it has stopped, you need to log in to your JupyterHub & start it again. You do not need a new token though.
- Watch out for filesystem access. When you are calling
open()(or a helper function that eventually access a file) to read a file, it is going to be read from your remote JupyterHub server’s home directory, not your local system’s current directory. So if you add a new file next to your Jupyter Notebook locally, that is not automatically going to be available to the Jupyter Notebook to read. - Installing pip or conda packages locally will have no effect, since your Python kernel is running on your JupyterHub. Use the %pip or %conda magics to install packages in the correct environment.
