Run Jupyter Notebook on a VPS and Connect via SSH Tunnel

This guide explains how to run a Jupyter Notebook server on a virtual private server (VPS) and securely connect to it from your local machine using an SSH tunnel. You’ll be able to access your notebooks in a local browser, with all traffic encrypted through the SSH connection. You’ll need a VPS with SSH access (typically Ubuntu or Debian), a local computer with a terminal (Linux/macOS) or PowerShell (Windows), and basic familiarity with the command line.

What You’ll Need

• A VPS (any provider) with SSH access and a public IP address.
• Python 3 and pip installed on the VPS (most distributions include them).
• An SSH client on your local machine (OpenSSH is built into Linux, macOS, and Windows 10+).
• Optional: a domain name pointing to your VPS, but an IP address works fine.

Step-by-Step

1. Connect to your VPS via SSH. Open a terminal on your local machine and run: ssh user@your_server_ip. Replace user with your SSH username (often root or a sudo user) and your_server_ip with the VPS’s IP address.
2. Install Python and pip if not already present. On Ubuntu/Debian, run: sudo apt update then sudo apt install python3 python3-pip python3-venv. On CentOS/RHEL, use sudo yum install python3 python3-pip.
3. Create a virtual environment (recommended). Run: python3 -m venv jupyter_env then activate it with source jupyter_env/bin/activate. This keeps your Jupyter installation isolated from system packages.
4. Install Jupyter Notebook. With the virtual environment active, run: pip install jupyter. This installs the classic notebook interface and its dependencies.
5. Generate a Jupyter configuration file. Run jupyter notebook --generate-config. This creates ~/.jupyter/jupyter_notebook_config.py.
6. Set a secure password for Jupyter. Run jupyter notebook password. Follow the prompts to enter a strong password. This stores a hashed password in ~/.jupyter/jupyter_notebook_config.json.
7. Edit the configuration file. Open the config file with nano ~/.jupyter/jupyter_notebook_config.py (or your preferred editor). Add or uncomment these lines:

   c.NotebookApp.allow_remote_access = True
   c.NotebookApp.ip = '127.0.0.1'
   c.NotebookApp.port = 8888
   c.NotebookApp.open_browser = False

   The ip setting is critical: binding to localhost means only connections from the VPS itself can reach the server, which is exactly what we want for an SSH tunnel. Save and exit.

8. Start the Jupyter server. Run jupyter notebook. It should start and print a URL like http://127.0.0.1:8888/?token=...&token=.... Leave this terminal running (or use nohup jupyter notebook & to keep it running after you log out).
9. Create the SSH tunnel from your local machine. Open a new terminal on your local machine (not the VPS) and run: ssh -N -L 8888:127.0.0.1:8888 user@your_server_ip. The -N flag tells SSH not to open a remote shell, -L forwards local port 8888 to the remote address. Leave this terminal open.
10. Access Jupyter in your browser. Open http://localhost:8888 on your local machine. You’ll see the Jupyter login page. Enter the password you set in step 6 (or the token from the startup URL if you didn’t set a password). You should now see the notebook dashboard.
11. Stop the server when done. To stop Jupyter, press Ctrl+C in the VPS terminal where it’s running. To close the tunnel, press Ctrl+C in the local terminal running the SSH command.

Common Mistakes

• Binding to 0.0.0.0 instead of 127.0.0.1. This exposes Jupyter to the public internet, which is dangerous. Always keep the bind address as 127.0.0.1.
• Forgetting the -N flag in SSH. Without it, the command opens a shell on the VPS and the tunnel may not work as expected.
• Using a different port. If you change the Jupyter port in the config, you must also change the port in the SSH command.
• Not activating the virtual environment. If you use a venv, you must activate it before running jupyter, or the system-wide Jupyter may be used.
• Firewall blocking. Some VPS providers have a firewall that blocks incoming connections. For an SSH tunnel, you only need port 22 (SSH) open; Jupyter’s port 8888 can be closed since it’s only accessed via the tunnel.

Tips

• Use SSH keys instead of passwords. This is more secure and allows you to connect without typing a password each time. Generate a key pair locally with ssh-keygen and copy the public key to the VPS with ssh-copy-id.
• Keep the Jupyter server running with nohup or a process manager. Using nohup jupyter notebook > jupyter.log 2>&1 & lets the server keep running after you log out. For a more robust setup, consider using systemd to manage the service.
• Use a different local port if 8888 is occupied. For example, ssh -N -L 9999:127.0.0.1:8888 and then visit http://localhost:9999.
• Set a custom notebook directory. In the config, add c.NotebookApp.notebook_dir = '/path/to/notebooks' to start Jupyter in a specific folder.
• Use a terminal multiplexer like tmux or screen. This lets you detach and reattach to the Jupyter session, which is handy if you need to check logs.

Troubleshooting

• Connection refused when opening localhost:8888. Check that the SSH tunnel is still running (the terminal should be open). Also verify Jupyter is running on the VPS by checking the terminal output. If you used nohup, check the log file with cat jupyter.log.
• Jupyter starts but you get a 403 Forbidden. This usually means you’re using an old token or the password isn’t set correctly. Run jupyter notebook password again and restart Jupyter.
• Cannot connect via SSH (timeout or permission denied). Ensure your VPS firewall allows SSH (port 22). If you’re using a key, make sure the private key is available locally and the public key is in ~/.ssh/authorized_keys on the VPS.
• Jupyter starts but no output appears. Check if the port is already in use. Run lsof -i :8888 on the VPS to see if another process is using it. If so, change the port in the config.
• Slow performance. This can be due to network latency or insufficient VPS resources. Consider upgrading your VPS plan or using a lighter kernel (e.g., jupyter lab is heavier).

Frequently Asked Questions

Is it safe to expose Jupyter to the internet if I use a password?

No, it’s not recommended. Even with a password, Jupyter can be vulnerable to brute-force attacks and security exploits. The SSH tunnel method keeps the server bound to localhost, so it’s never directly exposed.

Can I use Jupyter Lab instead of the classic notebook?

Yes. Install with pip install jupyterlab and run jupyter lab instead of jupyter notebook. The SSH tunnel setup is identical.

What if I want to access the notebook from a mobile device?

You can use an SSH client app (like Termius or Prompt) on your phone to create the tunnel, then open the browser to localhost:8888. The steps are the same.

Can I use this method with a Windows local machine?

Yes. Open PowerShell and run the same SSH command. If you don’t have OpenSSH, install it via Windows Settings > Apps > Optional Features.

How do I stop the Jupyter server if I used nohup?

Find the process ID with pgrep -f jupyter and then kill it with kill <PID>. Or use pkill -f jupyter to kill all Jupyter processes.

Can I use a different SSH port?

Yes, if your VPS SSH server runs on a non-standard port, add -p port_number to the SSH command, e.g., ssh -N -L 8888:127.0.0.1:8888 -p 2222 user@server.

Related

• Word Show or Hide Formatting Marks
• Phantom Blade Zero: Is It a Soulslike?
• 1Password vs LastPass: Which Password Manager Is Better?