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

Here’s how to run an IPython Notebook (now called a Jupyter Notebook) on a remote linux machine without using VNC.

These instructions are expanded on from here,
and it’s worth reading through to get more details.

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 have the code execute on the remote_machine.

Step 1: ssh into the remote machine from your local machine

[jer@local_machine ~]$ ssh remote_machine

Step 2 [optional]: On the remote_machine, run screen
Run screen in case this session gets closed, everything will keep running:

[jer@remote_machine ~]$ screen

Step 3: On the remote_machine, navigate to your IPython Notebook:

[jer@remote_machine ~]$ cd //path/to/my/code

Step 4: On the remote_machine, run the notebook with these flags

[jer@remote_machine ~]$ jupyter notebook --no-browser --port=8889

where the --no-browser means don’t open the internet browser, and --port=8889 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:
[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

[jer@local_machine ~]$ ssh -N -f -L jer@remote_machine

This sets the port 8889 on your local_machine to forward to port 8889 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,

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 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,

[jer@local_machine ~]$ ps aux | grep

or try,

[jer@local_machine ~]$ 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:8889:localhost:8889 jer@remote_machine

Change 21693 to the id you see, and run from the command line on your local_machine,

[jer@local_machine ~] kill 21693

And that should end the port forwarding!

Questions/comments? If you just want to say thanks, consider sharing this article or following me on Twitter!