🙌 Sirin's Note

Jupyter Setup

8 min read

Prerequisites

  • Python 3.6+ installed
  • pip (Python package manager)
  • Network access to the server (if setting up for remote access)
  • Basic command line knowledge

Installation Guide

Step 1: Install Jupyter Notebook

# Install Jupyter using pip
pip install jupyter
 
# For the full JupyterLab experience (recommended)
pip install jupyterlab

For a virtual environment installation (recommended):

# Create a virtual environment
python -m venv jupyter_env
 
# Activate the virtual environment
# On Windows:
jupyter_env\Scripts\activate
# On macOS/Linux:
source jupyter_env/bin/activate
 
# Install Jupyter in the virtual environment
pip install jupyter jupyterlab

Step 2: Create a Configuration File

Generate a default configuration file:

# For Jupyter Notebook
jupyter notebook --generate-config
 
# For JupyterLab
jupyter lab --generate-config

This will create a configuration file at:

  • Windows: C:\Users\USERNAME\.jupyter\jupyter_notebook_config.py
  • macOS/Linux: ~/.jupyter/jupyter_notebook_config.py

Server Configuration

Basic Configuration Options

Edit the configuration file to customize your Jupyter server settings:

# Set the IP address to listen on (0.0.0.0 to listen on all interfaces)
c.NotebookApp.ip = '0.0.0.0'
 
# Set the port to run the server on
c.NotebookApp.port = 8888
 
# Disable automatic opening of browser (useful for remote servers)
c.NotebookApp.open_browser = False
 
# Set a specific directory to serve notebooks from
c.NotebookApp.notebook_dir = '/path/to/your/notebooks'
 
# Allow remote access
c.NotebookApp.allow_remote_access = True
 
# Require a password or token for access (recommended for security)
# Option 1: Set a password
c.NotebookApp.password = 'sha1:password_hash'  # Use the command below to generate
 
# Option 2: Use a token for authentication
c.NotebookApp.token = 'your_custom_token'  # Or leave blank for random token

Setting a Password

Generate a password hash for your configuration:

jupyter notebook password

This will prompt you to enter and verify a password, then it will save the hashed password to your configuration file automatically.

Alternatively, generate a hash manually:

from notebook.auth import passwd
passwd()  # Enter and confirm your password when prompted
# Copy the resulting hash into your config file

Running Jupyter in the Background

Using nohup (Linux/macOS)

# Start Jupyter Notebook in the background
nohup jupyter notebook --no-browser --port=8888 --ip=0.0.0.0 &
 
# Start JupyterLab in the background
nohup jupyter lab --no-browser --port=8888 --ip=0.0.0.0 &

The nohup command ensures that the process keeps running even if you close your terminal, and the & runs it in the background.

Using screen or tmux (Linux/macOS)

These tools allow you to create detachable terminal sessions:

Using screen:

# Install screen if not already installed
# On Ubuntu/Debian:
sudo apt-get install screen
# On CentOS/RHEL:
sudo yum install screen
 
# Start a new screen session
screen -S jupyter
 
# Inside the screen session, start Jupyter
jupyter notebook --no-browser --port=8888 --ip=0.0.0.0
 
# Detach from the screen session (keep Jupyter running)
# Press Ctrl+A, then D
 
# To reattach to the screen session later
screen -r jupyter

Using tmux:

# Install tmux if not already installed
# On Ubuntu/Debian:
sudo apt-get install tmux
# On CentOS/RHEL:
sudo yum install tmux
 
# Start a new tmux session
tmux new -s jupyter
 
# Inside the tmux session, start Jupyter
jupyter notebook --no-browser --port=8888 --ip=0.0.0.0
 
# Detach from the tmux session (keep Jupyter running)
# Press Ctrl+B, then D
 
# To reattach to the tmux session later
tmux attach -t jupyter

Using systemd (Linux)

For a more permanent solution, create a systemd service:

# Create a systemd service file
sudo nano /etc/systemd/system/jupyter.service

Add the following content, replacing the paths and user as needed:

[Unit]
Description=Jupyter Notebook Server
After=network.target

[Service]
Type=simple
User=your_username
ExecStart=/home/your_username/jupyter_env/bin/jupyter notebook --config=/home/your_username/.jupyter/jupyter_notebook_config.py
WorkingDirectory=/home/your_username/notebooks
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

Then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable jupyter
sudo systemctl start jupyter
 
# Check the status
sudo systemctl status jupyter

Using Windows Task Scheduler (Windows)

  1. Open Task Scheduler (search for it in the Start menu)
  2. Click “Create Basic Task”
  3. Give it a name (e.g., “Jupyter Notebook Server”)
  4. Select “When I log on” as the trigger
  5. Choose “Start a program” as the action
  6. For the program/script, enter: pythonw (to run without console)
  7. For arguments, enter: -m jupyter notebook --config=C:\path\to\jupyter_notebook_config.py
  8. Check “Open the Properties dialog” and click “Finish”
  9. In the Properties dialog:
    • Go to the “Conditions” tab and uncheck “Start the task only if the computer is on AC power”
    • Go to the “Settings” tab and check “Run task as soon as possible after a scheduled start is missed”
    • Click “OK” to save

Accessing Your Jupyter Server

Local Access

If you’re running Jupyter on your local machine with default settings:

  • Open a web browser and navigate to: http://localhost:8888

Remote Access

If you’ve configured Jupyter to listen on all interfaces (IP 0.0.0.0):

  • From another machine on the same network: http://server_ip_address:8888
  • Over the internet (if properly forwarded): http://your_public_ip:8888

You’ll need the token or password you configured to log in. If you didn’t set one, check the terminal output when you started Jupyter for the automatically generated token.

Finding the Access Token

If you’ve lost your token, you can find it by running:

jupyter notebook list

This will show all running notebook servers and their tokens.

Securing Your Jupyter Server for Remote Access

Using SSL/HTTPS

Generate a self-signed certificate:

cd ~/.jupyter
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.key -out mycert.pem

Update your configuration file:

c.NotebookApp.certfile = '/home/your_username/.jupyter/mycert.pem'
c.NotebookApp.keyfile = '/home/your_username/.jupyter/mykey.key'

Now your Jupyter server will use HTTPS, accessible at https://server_ip:8888

Using SSH Tunneling

For added security, you can access Jupyter through an SSH tunnel instead of exposing it directly:

  1. Start Jupyter to listen only on localhost:
# In jupyter_notebook_config.py
c.NotebookApp.ip = '127.0.0.1'
c.NotebookApp.port = 8888
  1. Create an SSH tunnel from your local machine:
ssh -L 8888:localhost:8888 username@remote_server_ip
  1. Access Jupyter in your local browser at http://localhost:8888

Managing Running Jupyter Servers

Listing Running Servers

jupyter notebook list

Stopping a Server

If you started Jupyter in the foreground, press Ctrl+C twice to stop it.

For background processes:

# Find the process ID (PID)
ps aux | grep jupyter
 
# Kill the process
kill PID

If using systemd:

sudo systemctl stop jupyter

Common Troubleshooting

Port Already in Use

If you see an error that the port is already in use:

# Find what's using port 8888
# On Linux/macOS:
lsof -i :8888
# On Windows:
netstat -ano | findstr :8888
 
# Either kill that process or choose a different port
jupyter notebook --port=8889

Connection Refused

If you get “Connection refused” when trying to access Jupyter remotely:

  1. Confirm Jupyter is running with jupyter notebook list
  2. Verify you’re using the correct IP and port
  3. Check firewall settings:
# On Ubuntu/Debian:sudo ufw allow 8888# On CentOS/RHEL:sudo firewall-cmd --permanent --add-port=8888/tcpsudo firewall-cmd --reload

Missing Dependencies

If you encounter module import errors when using Jupyter:

# Install common data science libraries
pip install numpy pandas matplotlib scipy scikit-learn seaborn

Complete Example

Here’s a complete example for setting up a secure, remotely accessible Jupyter server:

# Create a virtual environment
python -m venv ~/jupyter_env
source ~/jupyter_env/bin/activate
 
# Install Jupyter and common libraries
pip install jupyter jupyterlab numpy pandas matplotlib scipy scikit-learn
 
# Generate a configuration file
jupyter notebook --generate-config
 
# Set a password
jupyter notebook password
 
# Generate SSL certificate
mkdir -p ~/.jupyter/ssl
cd ~/.jupyter/ssl
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout server.key -out server.pem
 
# Edit the configuration file
cat << EOF >> ~/.jupyter/jupyter_notebook_config.py
c.NotebookApp.ip = '0.0.0.0'
c.NotebookApp.port = 8888
c.NotebookApp.open_browser = False
c.NotebookApp.notebook_dir = '~/notebooks'
c.NotebookApp.allow_remote_access = True
c.NotebookApp.certfile = '~/.jupyter/ssl/server.pem'
c.NotebookApp.keyfile = '~/.jupyter/ssl/server.key'
EOF
 
# Create notebooks directory
mkdir -p ~/notebooks
 
# Create a systemd service
sudo tee /etc/systemd/system/jupyter.service > /dev/null << EOF
[Unit]
Description=Jupyter Notebook Server
After=network.target
 
[Service]
Type=simple
User=$(whoami)
ExecStart=$(which jupyter) notebook --config=/home/$(whoami)/.jupyter/jupyter_notebook_config.py
WorkingDirectory=/home/$(whoami)/notebooks
Restart=on-failure
RestartSec=30
 
[Install]
WantedBy=multi-user.target
EOF
 
# Start and enable the service
sudo systemctl daemon-reload
sudo systemctl enable jupyter
sudo systemctl start jupyter
 
# Check the status
sudo systemctl status jupyter
 
# Open firewall port if needed
sudo ufw allow 8888
 
# Show the URL for accessing Jupyter
echo "Your Jupyter Notebook server should now be accessible at: https://$(hostname -I | awk '{print $1}'):8888"
echo "Use the password you set earlier to log in."

Summary of Common Commands

# Install Jupyter
pip install jupyter jupyterlab
 
# Generate configuration
jupyter notebook --generate-config
 
# Set password
jupyter notebook password
 
# Start Jupyter Notebook in foreground
jupyter notebook
 
# Start Jupyter Notebook in background
nohup jupyter notebook --no-browser --port=8888 --ip=0.0.0.0 &
 
# Start JupyterLab in background
nohup jupyter lab --no-browser --port=8888 --ip=0.0.0.0 &
 
# List running servers
jupyter notebook list
 
# Stop all Jupyter servers
pkill jupyter
 
# Create a systemd service
sudo systemctl enable jupyter
sudo systemctl start jupyter
sudo systemctl status jupyter
sudo systemctl stop jupyter
 
# Access via SSH tunnel
ssh -L 8888:localhost:8888 username@remote_server_ip

Graph View

Backlinks