Python Environment Setup

Overview

A properly configured Python environment is essential for working with Sphinx and Jupyter notebooks. This guide covers setting up local environments using modern tools like UV and traditional venv, as well as connecting to remote Jupyter servers.

Recommendation: Use UV for new projects. It’s significantly faster than pip and provides better dependency resolution.

Python Installation

Before setting up environments, ensure Python 3.8 or higher is installed:

macOS
Windows
Linux

# Using Homebrew (recommended)
brew install [email protected]

# Or download from python.org
# https://www.python.org/downloads/

Download the installer from python.org or use winget:

# Using winget (Windows 10+)
winget install Python.Python.3.11

# During installation, check "Add Python to PATH"

Verify installation:

python --version

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip python3-venv

# Fedora
sudo dnf install python3 python3-pip

# Arch Linux
sudo pacman -S python python-pip

Verify installation:

python3 --version

Local Environment Setup

UV (Recommended)
venv (Standard Library)
Conda

UV is a fast Python package manager written in Rust that handles virtual environments and dependencies.

Install UV

macOS / Linux
Windows
Homebrew

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

brew install uv

Create a Project with UV

# Create a new project directory
mkdir my-analysis && cd my-analysis

# Initialize a UV project (creates pyproject.toml)
uv init

# Create virtual environment and install data science packages
uv add pandas numpy matplotlib seaborn scikit-learn scipy ipykernel

Register the Kernel with Jupyter

# Activate the environment and register the kernel
uv run python -m ipykernel install --user --name my-analysis --display-name "Python (my-analysis)"

Project Structure

After setup, your project should look like:

my-analysis/
├── .venv/              # Virtual environment (managed by UV)
├── pyproject.toml      # Project dependencies
├── uv.lock             # Locked dependency versions
└── notebooks/          # Your Jupyter notebooks

UV automatically creates and manages the .venv directory. You don’t need to activate it manually—use uv run to execute commands in the environment.

Adding Packages Later

# Add a new package
uv add plotly

# Add a development dependency
uv add --dev pytest

# Sync environment with lock file
uv sync

Python’s built-in venv module creates lightweight virtual environments without additional tools.

Create a Virtual Environment

macOS / Linux
Windows

# Create project directory
mkdir my-analysis && cd my-analysis

# Create virtual environment
python3 -m venv .venv

# Activate the environment
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Create project directory
mkdir my-analysis && cd my-analysis

# Create virtual environment
python -m venv .venv

# Activate the environment
.venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

Install Data Science Packages

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

# Install Jupyter kernel support
pip install ipykernel

# Register the kernel
python -m ipykernel install --user --name my-analysis --display-name "Python (my-analysis)"

Create a Requirements File

# Save current dependencies
pip freeze > requirements.txt

Your requirements.txt should include:

pandas>=2.0.0
numpy>=1.24.0
matplotlib>=3.7.0
seaborn>=0.12.0
scikit-learn>=1.3.0
scipy>=1.11.0
ipykernel>=6.25.0

Recreate Environment from Requirements

# Create fresh environment
python3 -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install from requirements
pip install -r requirements.txt

Conda is popular in data science for managing environments and non-Python dependencies.

Install Miniconda

macOS
Windows
Linux

# Using Homebrew
brew install miniconda

# Or download the installer
# https://docs.conda.io/en/latest/miniconda.html

Download the Windows installer and run it, or use winget:

winget install Anaconda.Miniconda3

After installation, open Anaconda Prompt from the Start menu to use conda commands.

# Download and install
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

# Follow the prompts, then restart your terminal

Create a Conda Environment

# Create environment with Python 3.11
conda create -n my-analysis python=3.11 -y

# Activate the environment
conda activate my-analysis

# Install data science packages
conda install pandas numpy matplotlib seaborn scikit-learn scipy ipykernel -y

# Register the kernel
python -m ipykernel install --user --name my-analysis --display-name "Python (my-analysis)"

Export Environment

# Export to YAML file
conda env export > environment.yml

Recreate from YAML

conda env create -f environment.yml

VS Code Configuration

Select Your Python Interpreter

Open VS Code Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Run “Python: Select Interpreter”
Choose your virtual environment (.venv or conda environment)

VS Code should show your environment in the status bar, e.g., Python 3.11.0 ('.venv': venv)

Select Jupyter Kernel

When you open a .ipynb file:

Click the kernel selector in the top-right corner
Select your registered kernel (e.g., “Python (my-analysis)”)
The kernel should start and show as connected

If your kernel doesn’t appear, ensure you ran the ipykernel install command and restart VS Code.

Recommended VS Code Extensions

Install these extensions for the best Jupyter experience:

Extension	Purpose
Python	Python language support
Jupyter	Notebook support (required for Sphinx)
Pylance	Fast IntelliSense and type checking

Remote Jupyter Server

Connect to a Jupyter server running on a remote machine, cloud instance, or HPC cluster.

Start a Remote Jupyter Server

On the remote machine:

# Install Jupyter
pip install jupyter

# Start server with remote access
jupyter notebook --no-browser --ip=0.0.0.0 --port=8888

The server will output a URL with a token:

http://127.0.0.1:8888/?token=abc123...

Security: Never expose Jupyter servers to the public internet without authentication. Use SSH tunneling for secure connections.

Connect VS Code to Remote Server

Open VS Code Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Run “Jupyter: Specify Jupyter Server for Connections”
Select “Existing”
Enter the server URL: http://localhost:8888/?token=abc123...
Your remote kernels should now appear in the kernel picker

JupyterHub Connection

For enterprise JupyterHub deployments:

Get your JupyterHub URL (e.g., https://hub.company.com)
Follow the same connection steps as above
Authenticate with your JupyterHub credentials
Select from available hub-managed kernels

Some JupyterHub deployments require an API token. Generate one from the JupyterHub web interface under Token settings.

Best Practices

One environment per project

Avoid using a single global environment. Create dedicated environments for each project to prevent dependency conflicts and ensure reproducibility.

# Good: Project-specific environment
my-project/.venv/

# Bad: Global environment shared across projects
~/.global-venv/

Pin your dependencies

Always pin package versions for reproducible environments:UV (pyproject.toml):

[project]
dependencies = [
    "pandas>=2.0.0,<3.0.0",
    "numpy>=1.24.0,<2.0.0",
]

pip (requirements.txt):

pandas==2.1.4
numpy==1.26.3

UV automatically creates a uv.lock file for exact reproducibility.

Use .gitignore for virtual environments

Never commit virtual environments to version control:

# .gitignore
.venv/
venv/
env/
__pycache__/
*.pyc
*.pyo
.ipynb_checkpoints/
*.egg-info/
dist/
build/

Cross-platform note: Use forward slashes (/) in .gitignore even on Windows—Git handles the conversion automatically.

Document your setup

Include setup instructions in your project README:

## Setup

Install UV: `curl -LsSf https://astral.sh/uv/install.sh | sh`
Install dependencies: `uv sync`
Register kernel: `uv run python -m ipykernel install --user --name my-project`
Open VS Code and select the kernel

Keep environments minimal

Only install packages you actually need. Large environments are slow to create and can have dependency conflicts.

# Good: Install what you need
uv add pandas matplotlib

# Avoid: Installing everything "just in case"
uv add pandas numpy scipy matplotlib seaborn plotly bokeh altair ...

Use pyproject.toml for modern projects

pyproject.toml is the modern standard for Python project configuration:

[project]
name = "my-analysis"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "pandas>=2.0.0",
    "matplotlib>=3.7.0",
    "ipykernel>=6.25.0",
]

[project.optional-dependencies]
dev = ["pytest", "black", "ruff"]

Troubleshooting

Kernel not appearing in VS Code

Ensure ipykernel is installed in your environment

Run the kernel install command:

python -m ipykernel install --user --name my-env --display-name "Python (my-env)"

Restart VS Code
Check “Jupyter: Select Interpreter to Start Jupyter Server” in Command Palette

Package import errors in notebook

The notebook might be using a different kernel than expected:

Check the active kernel in the top-right of the notebook
Ensure it matches your environment with the installed packages
Restart the kernel after installing new packages

UV command not found

Add UV to your PATH:

macOS / Linux
Windows

# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/.cargo/bin:$PATH"

Then restart your terminal or run source ~/.zshrc.

The UV installer should add it to PATH automatically. If not:

Open System Properties → Environment Variables
Under User variables, edit Path
Add: %USERPROFILE%\.cargo\bin
Click OK and restart your terminal

Or use PowerShell:

$env:Path += ";$env:USERPROFILE\.cargo\bin"
[Environment]::SetEnvironmentVariable("Path", $env:Path, "User")

Remote kernel disconnects frequently

Check network stability

Increase Jupyter timeout settings on the server:

jupyter notebook --NotebookApp.shutdown_no_activity_timeout=3600

Consider using VS Code Remote - SSH extension for a more stable connection

Permission denied when installing kernel

Use the --user flag to install kernels in your user directory:

python -m ipykernel install --user --name my-env

Or use --prefix for a specific location:

python -m ipykernel install --prefix=/path/to/kernels --name my-env

'python' is not recognized (Windows)

If you see this error on Windows:

Ensure Python is installed: winget install Python.Python.3.11
Check Add Python to PATH was selected during installation
Manually add Python to PATH:
- Open System Properties → Environment Variables
- Under User variables, edit Path
- Add: C:\Users\YourUsername\AppData\Local\Programs\Python\Python311
- Add: C:\Users\YourUsername\AppData\Local\Programs\Python\Python311\Scripts
Restart your terminal

Alternatively, use the Python Launcher:

py -m venv .venv
py -m pip install package-name

Python command differences (Linux/Mac vs Windows)

Linux/macOS:

Use python3 and pip3 to avoid Python 2.x conflicts
Example: python3 -m venv .venv

Windows:

Use python (Python 3 is the default)
Or use py launcher: py -3.11 -m venv .venv

Cross-platform script:

# Works on all platforms
python -m venv .venv  # or python3 on Linux/macOS

Quick Reference

UV Commands

Command	Description
`uv init`	Initialize new project
`uv add <package>`	Add dependency
`uv remove <package>`	Remove dependency
`uv sync`	Sync environment with lock file
`uv run <command>`	Run command in environment
`uv lock`	Update lock file

venv Commands

Command	Description
`python -m venv .venv`	Create environment
`source .venv/bin/activate`	Activate (macOS/Linux)
`.venv\Scripts\activate`	Activate (Windows)
`deactivate`	Deactivate environment
`pip freeze > requirements.txt`	Export dependencies

Kernel Commands

Command	Description
`python -m ipykernel install --user --name <name>`	Register kernel
`jupyter kernelspec list`	List installed kernels
`jupyter kernelspec uninstall <name>`	Remove kernel

Home

Extension

CLI

Agent

Configuration

Python Environment Setup

Overview

Python Installation

Local Environment Setup

Install UV

Create a Project with UV

Register the Kernel with Jupyter

Project Structure

Adding Packages Later

Create a Virtual Environment

Install Data Science Packages

Create a Requirements File

Recreate Environment from Requirements

Install Miniconda

Create a Conda Environment

Export Environment

Recreate from YAML

VS Code Configuration

Select Your Python Interpreter

Select Jupyter Kernel

Recommended VS Code Extensions

Remote Jupyter Server

Start a Remote Jupyter Server

Connect VS Code to Remote Server

JupyterHub Connection

Best Practices

Troubleshooting

Quick Reference

UV Commands

venv Commands

Kernel Commands

Home

Extension

CLI

Agent

Configuration

​Overview

​Python Installation

​Local Environment Setup

​Install UV

​Create a Project with UV

​Register the Kernel with Jupyter

​Project Structure

​Adding Packages Later

​Create a Virtual Environment

​Install Data Science Packages

​Create a Requirements File

​Recreate Environment from Requirements

​Install Miniconda

​Create a Conda Environment

​Export Environment

​Recreate from YAML

​VS Code Configuration

​Select Your Python Interpreter

​Select Jupyter Kernel

​Recommended VS Code Extensions

​Remote Jupyter Server

​Start a Remote Jupyter Server

​Connect VS Code to Remote Server

​JupyterHub Connection

​Best Practices

​Troubleshooting

​Quick Reference

​UV Commands

​venv Commands

​Kernel Commands

Overview

Python Installation

Local Environment Setup

Install UV

Create a Project with UV

Register the Kernel with Jupyter

Project Structure

Adding Packages Later

Create a Virtual Environment

Install Data Science Packages

Create a Requirements File

Recreate Environment from Requirements

Install Miniconda

Create a Conda Environment

Export Environment

Recreate from YAML

VS Code Configuration

Select Your Python Interpreter

Select Jupyter Kernel

Recommended VS Code Extensions

Remote Jupyter Server

Start a Remote Jupyter Server

Connect VS Code to Remote Server

JupyterHub Connection

Best Practices

Troubleshooting

Quick Reference

UV Commands

venv Commands

Kernel Commands