Last Updated: December 18, 2019
· cheglastgnat

Remote Access to IPython Notebooks via SSH

Scenario: On your local computer, you want to open and manipulate an IPython notebook running on a remote computer. We will do this by opening an SSH tunnel. This tunnel will forward the port used by the remotely running IPython instance to a port on the local machine, where it can be accessed in a browser just like a locally running IPython instance.

On the remote machine, start the IPython notebooks server:

remote_user@remote_host$ ipython notebook --no-browser --port=8889

Usually IPython opens a browser to display the available notebooks, but we do not need that so we use the option --no-browser. We also change the port to 8889, for no other reason than to show how this is done.

On the local machine, start an SSH tunnel:

local_user@local_host$ ssh -N -f -L localhost:8888:localhost:8889 remote_user@remote_host

The first option -N tells SSH that no remote commands will be executed, and is useful for port forwarding. The second option -f has the effect that SSH will go to background, so the local tunnel-enabling terminal remains usable. The last option -L lists the port forwarding configuration (remote port 8889 to local port 8888).

Now open your browser on the local machine and type in the address bar


which displays your remotely running IPython notebook server.

To close the SSH tunnel on the local machine, look for the process and kill it manually:

local_user@local_host$ ps aux | grep localhost:8889
local_user 18418  0.0  0.0  41488   684 ?        Ss   17:27   0:00 ssh -N -f -L localhost:8888:localhost:8889 remote_user@remote_host
local_user 18424  0.0  0.0  11572   932 pts/6    S+   17:27   0:00 grep localhost:8889

local_user@local_host$ kill -15 18418

Alternatively, you can start the tunnel without the -f option. The process will then remain in the foreground and can be killed with ctrl-c.

On the remote machine, kill the IPython server with ctrl-c ctrl-c.

23 Responses
Add your response


This does not work when I have to use SSH to get to the remote machine to start the IPython notebooks server, right?

over 1 year ago ·

That should work as well, yes. Is there a problem with the first step?

over 1 year ago ·

Oh, I am sorry. The first time I tried this, I couldn't start the second SSH tunnel on my local machine, and from the error I assumed that it's not possible. I thought if I have to open a "standard" SSH tunnel to start IPython notebooks server on the remote machine I would not be able to open a second one setting the port forwarding.
I was wrong, though, since it worked perfectly fine this time.

over 1 year ago ·

Ah, good to know it works! :)

By the way, you don't have to keep both ssh connections open. I usually use screen or tmux on the remote server to keep my remote session alive. This way, I only have to login once to start the IPython notebook server, then I can detach the session and logout.

over 1 year ago ·

I haven't heard of any of these before... but it seems we have screen on the server already! Thanks for the tip, I'll try that right away. :-)

over 1 year ago ·

Onn the browser I got "channel 2: open failed: connect failed: Connection refused" It works tunneling ssh -N -f -L localhost:8888: Juhuuuu!!!

over 1 year ago ·

Hi ilciavo, thanks for your comment! Perhaps there is a security setting on your machine which blocks that specific port of "localhost"?

over 1 year ago ·

I am getting the same error as ilviavo, but using the address doesn't work for me. I also get:
bind: Address already in use
channelsetupfwd_listener: cannot listen to port: 8888
Could not request local forwarding.

But searching for ps aux | grep localhost:8889 or ps aux | grep localhost:8888 doesn't show anything.

Any suggestions?

over 1 year ago ·

Hi Nic,
sounds like port 8888 might already be in use on your machine. If that's the case, it should show in the output of
"netstat -tulpn | grep 8888" (might need root)
You can try any other port above 1024 :)

over 1 year ago ·

Great tutorial! I want to add a tip for enabling display of remote figures (I got a DISPLAY error when the remote server executing my ipython notebook code didn't have anywhere to put Xwindows)

Although you can use XPRA to forward the entire browser window remotely, it's slow. Combining xpra for remote display of xwindows (e.g., matplotlib or mayavi figures), you can combine the advice from here (https://wiki.archlinux.org/index.php/Xpra)

remote@remote$ xpra start :100

remote@remote$ DISPLAY:=100 screen

remote@remote$ ipython notebook --no-browser --port=8889

local@local$ ssh -N -f -L localhost:8888:localhost:8889 remoteuser@remotehost

And you'll see figures opened on your remote machine pop up in xpra windows on your local machine

over 1 year ago ·

Hi phareaux,

thanks for the (pro)tip! Usually inline figures are good enough for me, but this sounds great.

over 1 year ago ·

Hi cheglastgnat,

I try to use inline figures as well, but unfortunately mayavi inlining in ipython notebook isn't (yet) well supported (screenshots, no interactivity). It doesn't seem to actually forward the interactive scenes (empty windows), but it doesn't give me errors.

over 1 year ago ·

If I need the ipython notebook process continues to run even if the ssh disconnect, simply remove the -f command? So I can access the process until new connection just reconnect ssh with the same port of the process?
I will make a parallel programming processing and machine learning, the training will last about 15 days and must monitor the process, would do via shell normally, but the idea of using the ipython notebook is extremely more satisfactory ...

over 1 year ago ·

As an amendment to my previous comment (about xpra), I think there's a simpler way to do X forwarding of a window outside of the ipython notebook environment. Also, the way I tried doing kept failing for awhile, so I got the below to work (also, there's a typo in the old DISPLAY=:Z string)

  1. create vnc server on remote host, which will allocate a new X display if necessary and tell you it as an integer: <outputfromvncserver> remote@remote$ vncserver
  2. either a. export the resulting display via remote@remote$ export DISPLAY=:<outputfromvncserver> and then start ipython notebook with command recommended by article (with same environment!) or 2b.
  3. start ipython notebook
    inside the notebook

    import os
    os.environ['DISPLAY'] = '<outputfromvncserver>'

  4. now you can use a vncviewer with something like
    local@local$ vncviewer remote@remote:<outputfromvncserver>

and you'll see a remote desktop appear, along with any mayavi figures (or other out-of-notebook X windows?) you might be using

over 1 year ago ·

Thanks so much

over 1 year ago ·

If you're on a secure network just pass -ip=* and you can connect it from all machines without SSH tunneling!

over 1 year ago ·

Nice tutorial.. Was precisely looking for this! :)

@phareaux: regarding X forwarding, is there a reason why X forwarding over ssh wouldn't work?

over 1 year ago ·

The kernel keeps disconnecting when I'm away from my seat. Sometimes I need the GPU running for hours to reach the end result; does anyone have solutions to this?

over 1 year ago ·

I'm trying to use this protocol, but when I try to create a new Python notebook in my browser the Jupyter notebook dies and no new notebook is created. No useful error is outputted either. Has anyone else encountered this problem?

over 1 year ago ·

I think that using same port on local and remote will be better for clarity, it is possible https://maketips.net/tip/148/forward-remote-port-to-local-using-ssh

over 1 year ago ·

This is an excellent tutorial. I have one question though: is it possible to run a python console side by side using the same kernel? I'm a fan of using Jupyter's qtconsole, but this requires me use XQuartz, which gives me a console with a UI that is quite sluggish.

over 1 year ago ·

worked with Jupyter Notebook following the exact instructions. many thanks

over 1 year ago ·

Thank you

3 months ago ·