How to Connect VS Code to a Jupyter Kernel on a Remote Machine

Your heavy Python environment lives somewhere else: on a cloud server, a university machine, a home server, or a GPU box under your desk. You want VS Code’s editing comfort with that remote machine’s power, and specifically, you want your notebooks to run on a Jupyter kernel over there. There are two solid ways to achieve this, and choosing the right one saves real frustration. This guide walks through both: connecting VS Code to an existing remote Jupyter server by URL, and using the Remote-SSH extension so the whole workspace lives on the remote machine.

Quick Answer

To run notebooks on a remote kernel, either start Jupyter on the remote machine and connect VS Code to it, or open the remote folder with Remote-SSH. For the first route: on the server run jupyter notebook --no-browser --port=8888, copy its token URL, then in VS Code open a notebook, click the kernel picker, choose Select Another Kernel → Existing Jupyter Server, and paste the URL. For the second route, connect with Remote-SSH, open the remote project, and pick the remote environment as the kernel exactly as you would locally.

Before You Start: What You Need

• VS Code on your local machine with the Python extension and the Jupyter extension installed.
• On the remote machine: Python with jupyter and ipykernel installed in the environment you plan to use. If kernels are new territory, our guide to fixing Jupyter kernel errors explains how kernels and environments relate.
• Network access from your machine to the server. If the server is not publicly reachable, an SSH tunnel (covered below) is the standard, secure bridge.
• The server’s Jupyter token or password. Token URLs look like http://localhost:8888/?token=abc123....

Method 1: Connect to an Existing Jupyter Server

1. Start Jupyter on the remote machine inside the environment you want: jupyter notebook --no-browser --port=8888. It prints one or more URLs containing a token. Keep this terminal open; closing it stops the server.
2. Make the server reachable. If you are on the same network and the server allows remote connections, you may use its address directly. More commonly, create an SSH tunnel from your local machine: ssh -L 8888:localhost:8888 user@server-address. With the tunnel up, the remote Jupyter behaves as if it were at your own localhost:8888, and the traffic is encrypted by SSH.
3. Point VS Code at the server. Open or create a .ipynb file, click the kernel name in the top-right of the notebook editor, choose Select Another Kernel, then Existing Jupyter Server, and paste the full URL including the token.
4. Pick the remote kernel. VS Code lists the kernels available on that server. Choose the environment you prepared. The notebook’s cells now execute on the remote machine, using its files, CPU, and memory.
5. Verify execution location. Run a cell printing import socket; print(socket.gethostname()) and confirm the host name is the server’s, not your laptop’s. This check prevents the classic confusion of thinking you are remote while actually running locally.

The official VS Code Jupyter documentation walks through the same kernel-picker flow with the current interface names.

Method 2: Use Remote-SSH for the Whole Workspace

If you also want to edit the server’s files, use its terminals, and debug on the server, Remote-SSH is the better fit. Install the Remote – SSH extension, connect to the host, and open the remote project folder. VS Code then runs a small server component on the remote machine, and everything — file explorer, terminal, Python extension, and notebook kernels — operates there. Select the kernel from the picker as usual; the environments listed are the remote machine’s. This route avoids running a separate Jupyter server at all, because VS Code manages kernels through the remote Python environments directly, which many people find less fiddly for day-to-day development.

Security Notes Worth Taking Seriously

• Prefer an SSH tunnel over exposing Jupyter to the internet. A token-protected server on a public port will be found and probed. The tunnel keeps Jupyter bound to localhost on the server and encrypts everything.
• Treat the token like a password. Anyone with it can execute code on the server as your user. Do not paste it into shared documents or screenshots.
• Consider a Jupyter password or a hub for shared machines, and shut the server down with Ctrl+C in its terminal when you finish long sessions.

Troubleshooting Common Snags

• “Connection failed” when selecting the server: the tunnel is down, the URL lacks the token, or the server was started on a different port. Re-copy the exact URL from the server’s terminal output.
• The kernel list is empty: the remote environment lacks ipykernel. Install it into that environment on the server and restart the Jupyter server.
• Cells run, but on the wrong machine: you selected a local kernel. Re-check with the host name test and reselect through the kernel picker; also confirm the notebook’s top-right indicator names the remote server.
• Files in the notebook are not where you expect: a remote kernel’s working directory is on the server. Relative paths resolve there, not on your laptop, so upload data files to the server or reference them by their remote paths. The interpreter-selection discipline from our guide on selecting the correct Python interpreter in VS Code applies here too: always confirm which environment a notebook is really using.

Choosing Between the Two Methods

A short decision guide saves experimentation. Choose the Existing Jupyter Server route when a Jupyter server already runs on the remote machine — perhaps one you started in a persistent terminal session or one provided by your institution — and your work is mainly notebooks. It is the lighter setup: one URL, one kernel picker, done. Choose Remote-SSH when you want the full project experience on the server: editing its files with the normal explorer, using its integrated terminal, running scripts and debuggers, and treating notebooks as one part of a larger codebase. It needs no separately running Jupyter server, since VS Code manages kernels through the remote environments itself. Many people end up using both: Remote-SSH for project development through the week, and the server connection for a quick notebook against a long-running shared machine. Neither is a compromise; they simply optimise for different kinds of sessions, and you can switch per task without disturbing the remote setup itself.

Conclusion

Connecting VS Code to a remote Jupyter kernel is a matter of starting the server where the power is, bridging the connection securely — ideally with an SSH tunnel — and selecting that server in the kernel picker. Choose the Existing Jupyter Server route for quick notebook work against a running server, and Remote-SSH when you want the entire project to live remotely. Verify with a host name check, and your laptop becomes a window onto the bigger machine.

Frequently Asked Questions

Do I need Jupyter installed on my local machine?

For the Existing Jupyter Server route, no. VS Code talks to the remote server, and all execution happens there; you only need the Python and Jupyter extensions locally. For local kernels you do need local environments, but remote connections offload everything to the server.

What is the difference between the kernel and the Jupyter server?

The server is the service that manages notebooks and spawns kernels; a kernel is one Python process, tied to one environment, that runs your cells. One server can offer several kernels for different environments. In VS Code you connect to a server, then choose among its kernels per notebook.

How do I reconnect quickly next time?

VS Code remembers recent Jupyter server URLs in the kernel picker, so reconnecting is usually two clicks once the server and tunnel are running again. For Remote-SSH, the host stays in the Remote Explorer list, and reopening the folder restores the whole setup, kernel selection included.

Can I connect to a remote kernel without SSH?

Yes, if the server is reachable over your network with its token URL, for example within a company VPN. The security reasoning still applies: only expose Jupyter on networks you trust, keep token secrecy, and prefer tunnelling or a properly managed JupyterHub for anything internet-facing.

Why is my remote kernel slow to start the first time?

First starts load the environment and extensions on the server and may contend with other users on shared machines. Later cell execution is what matters and should feel normal. If starts stay slow, check the server’s load and memory rather than your local machine, since the work happens there.