How to run an IPython/Jupyter Notebook on a remote machine

Here’s how to run an IPython/Jupyter Notebook on a remote Linux machine without using VNC. I expanded on these instructions.

Let’s assume you have two machines:
local-machine that you are physically working on
remote-machine that you want to run code on.

And you want to work in the browser on your local-machine, but execute the code on the remote-machine.

Here are the important lines you’re probably looking for:

jupyter notebook --no-browser --port=8898

ssh -N -f -L 127.0.0.1:8898:127.0.0.1:8898 jer@remote-machine

http://127.0.0.1:8898/

If you want complete and detailed steps, keep reading below!

Steps to Run a Remote Jupyter Notebook

• Step 1: ssh into the remote-machine

ssh jer@remote-machine

Don’t forget to change jer and remote-machine to your user and machine name!

• Step 2: [optional] On the remote-machine, run tmux

tmux

If your remote session gets disconnected, tmux will keep the session running (to reconnected run tmux attach)!

• Step 3: On the remote-machine, navigate to the folder containing your Jupyter Notebook:

cd //path/to/my/code 

• Step 4: On the remote-machine, run the notebook with these flags

jupyter notebook --no-browser --port=8898

where the --no-browser means don’t open the internet browser, and --port=8898 means to run it using this port. You can change the port number to something else as well.

This should start an IPython/Jupyter Notebook and you should see something like:

...
[I 10:54:08.168 NotebookApp] The IPython Notebook is running at: http://127.0.0.1:8898/
[I 10:54:08.168 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).

Note that you can close the Notebook on the remote-machine by typing Ctrl-C-C here.

• Step 5: On your local-machine, use ssh with port forwarding

ssh -N -f -L 127.0.0.1:8898:127.0.0.1:8898 jer@remote-machine

This sets the port 8898 on your local-machine to forward to port 8898 on your remote-machine. Make sure that this port number matches the port number in Step 4. You can also change the port numbers both on your remote and local machine as needed (and they do not have to match)

• Step 6: On your local-machine, open your internet browser and type in,

http://127.0.0.1:8898

And bam! You should see your notebook in your browser. Anything you do here, will be executed on the remote machine.

Now you should end the port forwarding when you are done. Read on to see how to do this.

Troubleshooting and ending port forwarding

If you get the error message,

bind: Address already in use
channel_setup_fwd_listener: cannot listen to port: 8889
Could not request local forwarding.

… then probably already have something running on that port.

You might already have an ipython session running on that port. You can either kill the session (shown below) or change the above port number from Step 4/5.

How to end port forwarding

Get the id of the job from the command line on your local-machine,

ps aux | grep 127.0.0.1

or if that doesn’t work, try,

ps aux | grep localhost

This should show something like,

jer 21693  0.0  0.0  72196  1004 ?        Ss   13:14   0:00 ssh -N -f -L localhost:8898:localhost:8898 jer@remote-machine

Change 21693 to the id you see, and run from the command line on your local-machine,

kill 21693

And that should end the port forwarding!