Environment Setup

Introduction

Setting up a proper development environment is crucial for data science work. This tutorial guides you through installing uv, the modern Python package manager, and understanding modern Python project standards with pyproject.toml configuration.

A well-configured environment ensures:

• Reproducibility: Your code works consistently across different machines
• Speed: Fast dependency installation and resolution
• Simplicity: No manual virtual environment management
• Modern Standards: Following current Python development practices

Prerequisites

• Basic command line knowledge
• Administrator/sudo access on your machine
• Internet connection for package downloads

Development Environment Setup

Visual Studio Code Installation

Visual Studio Code (VS Code) is the recommended IDE for this course. It provides excellent Python support, integrated terminal, and extensions for data science.

Installation:

1. Download VS Code:

   • Visit https://code.visualstudio.com/
   • Download for your operating system
   • Install with default settings

2. Essential Extensions:

   • Python: Official Python extension by Microsoft (provides IntelliSense, debugging, and code completion)
   • Pylance: Advanced Python language server (enhanced error detection and type checking)
   • Jupyter: Jupyter notebook support (edit and run notebooks directly in VS Code)
   • GitLens: Enhanced Git capabilities (version control integration within the editor)
   • Remote - WSL: For Windows users (enables seamless WSL integration)

3. Python Extension Setup:

   • Open VS Code
   • Install Python extension
   • Access integrated terminal (Ctrl+`` or View → Terminal) to run Python scripts directly

Platform-Specific Setup

Windows Users: WSL2 Setup

Why WSL2? Windows Subsystem for Linux provides a native Linux environment that ensures compatibility with most data science tools and matches deployment environments.

1. Enable WSL2:

   1 2	# Run in PowerShell as Administrator wsl --install

2. Install Ubuntu:

   1	wsl --install -d Ubuntu

3. Set up Ubuntu:

   • Launch Ubuntu from Start menu
   • Create username and password
   • Update packages: sudo apt update && sudo apt upgrade

4. Access from VS Code (recommended):

   • Install “Remote - WSL” extension
   • Open folder in WSL: code . from Ubuntu terminal

macOS and Linux Users

Your system is ready for Python development. Proceed to uv installation.

Modern Python Environment with uv

Why uv? uv is a modern Python package manager that combines the functionality of pip, virtualenv, and pyenv into a single, fast tool. It’s written in Rust and provides significant performance improvements over traditional tools. UV provide the following features:

• Automatic Python Installation: uv can install Python versions automatically
• Built-in Virtual Environments: No need to manually create or activate environments
• Fast Dependency Resolution: 10-100x faster than pip
• pyproject.toml Native: Works seamlessly with modern Python project standards
• Lock Files: Automatically creates uv.lock for exact reproducibility

Reference:

• Why Should I Choose pyproject.toml over requirements.txt for managing dependencies?

Install uv

All platforms:

1
2

# Install uv using the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

Verify installation:

1

uv --version

Si cela ne fonctionne pas il faut fermer et relancer votre path ou recharger votre shell en faisant par exemple source ~/.zshrc si vous utilisez zsh.

Working with uv

Creating Your First Project

1
2
3
4
5
6

# Create a new project with uv
uv init my-data-project
cd my-data-project

# Project structure is automatically created with pyproject.toml
ls -la

Python Version Management

1
2
3
4
5

# Install specific Python version
uv python install 3.11

# Check available Python versions
uv python list

Managing Dependencies

Proper dependency management is crucial for reproducible and maintainable data science projects. It ensures that your code works consistently across different environments and team members can easily set up the same development environment.

Understanding uv’s Dependency Files

When working with uv, two key files manage your project dependencies:

• pyproject.toml: Defines your project requirements and version constraints
• uv.lock: Contains exact pinned versions for reproducible installations

Adding Dependencies

1
2
3
4
5

# Add core dependencies
uv add pandas numpy matplotlib seaborn plotly scipy

# Add development dependencies
uv add --group dev jupyter pytest ipykernel

This creates a pyproject.toml file with your project configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

[build-system]
requires = ["setuptools~=80.9.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "sales_analysis"
version = "1.0.0"
description = "Sales Data Analysis Project"
requires-python = ">=3.11"

dependencies = [
    "pandas>=2.3.1",
    "numpy>=2.3.1",
    "matplotlib>=3.10.3",
    "seaborn>=0.13.2",
    "plotly>=5.15.0",
    "scipy>=1.16.1",
]

[dependency-groups]
dev = [
    "ipykernel>=6.29.5",
    "jupyter>=1.1.1",
    "pytest>=8.4.1"
]

Version Constraints:

• ~=2.3.1: Compatible release (allows 2.3.x but not 2.4.0)
• >=3.11: Minimum version required

Locking Dependencies

To ensure reproducible installations, lock your dependencies to exact versions:

1

uv lock

This generates uv.lock with pinned versions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

[[package]]
name = "pandas"
version = "2.3.1"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "numpy", version = "2.3.1" },
    { name = "python-dateutil", version = "2.9.0" },
    { name = "pytz", version = "2024.2" },
]

[[package]]
name = "numpy"
version = "2.3.1"
source = { registry = "https://pypi.org/simple" }

Installing the Virtual Environment

When joining a project or setting up on a new machine you can just import pyproject.toml and uv.lock files.

After importing these files or adding dependencies manually run the installation in an isolated virtual environment.

1
2

# Install (creates .venv/ directory)
uv sync

This command includes both core dependencies and dev group.

Examining the Environment

View your installed packages and their dependency tree:

1
2

# Show dependency tree
uv tree

Example output:

sales_analysis v1.0.0
├── pandas v2.3.1
│   ├── numpy v2.3.1
│   ├── python-dateutil v2.9.0
│   └── pytz v2024.2
├── matplotlib v3.10.3
│   └── numpy v2.3.1
└── seaborn v0.13.2
    ├── matplotlib v3.10.3
    └── pandas v2.3.1

Optional Dependencies

Organize dependencies into groups for different use cases:

1
2
3
4
5
6
7
8

# Add optional dependencies to specific groups
uv add --group ml scikit-learn xgboost
uv add --group viz plotly dash

# Install specific dependency groups
uv sync --group dev          # Development tools only
uv sync --group ml           # Machine learning packages
uv sync --all-groups         # All optional dependencies

This approach allows team members to install only the dependencies they need for their specific tasks.

Running Python Code

1
2
3
4
5

# Run Python scripts (automatically uses project environment)
uv run python my_script.py

# Run Jupyter notebook
uv run jupyter notebook

VSCode and Jupyter Notebooks with uv

Common Jupyter Kernel Issue

When working with Jupyter notebooks in VSCode using uv environments, you might encounter the “ipykernel not installed” error even though ipykernel is present in your pyproject.toml and correctly installed in the virtual environment.

Why does this happen?

• VSCode looks for Jupyter kernels in system-wide locations
• uv kernels are installed locally in the project’s .venv/ directory
• By default, VSCode cannot see these local kernels

Register the Kernel for VSCode

To make VSCode see and use your uv environment with Jupyter, register the kernel at the user level:

1
2
3
4
5
6
7
8

# Navigate to your uv project
cd /path/to/your/project

# Register the uv kernel for the current user
uv run python -m ipykernel install --user --name project_name --display-name "Project Name (uv)"

# Example for an air_quality project:
uv run python -m ipykernel install --user --name air_quality --display-name "Air Quality (uv)"

Command parameters:

• --user: Install for current user (no sudo required)
• --name: Technical kernel name (no spaces)
• --display-name: Display name in VSCode (can contain spaces)

Alternatively, you can in VSCode press CRTL+Shift+P and search Python: Select Interpreter and either choose the interpreter or specify the path to it. To find that path : uv run which python.

Configure Notebook kernel in VSCode

1. Restart VSCode completely to detect new kernels

2. Open your notebook (.ipynb file)

3. Select the kernel:

   • Click the kernel selector in the top-right of the notebook
   • Or use Ctrl+Shift+P → “Notebook: Select Notebook Kernel”

4. Choose your uv kernel:

   • Look for “Air Quality (uv)” in the list
   • Select the kernel with the name you specified

Modern Python Project Standards

Understanding pyproject.toml

Modern Python projects use pyproject.toml for configuration. This follows PEP 518 and PEP 621 standards and is automatically created by uv.

Example pyproject.toml structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-data-project"
version = "1.0.0"
description = "A data science project"
requires-python = ">=3.11"

dependencies = [
    "pandas>=2.0.0",
    "numpy>=1.24.0",
    "matplotlib>=3.7.0",
]

[project.optional-dependencies]
dev = ["pytest>=7.0.0", "jupyter>=1.0.0"]
ml = ["scikit-learn>=1.3.0", "xgboost>=1.7.0"]

Working with Optional Dependencies

1
2
3
4
5
6
7
8
9

# Install all dependencies
uv sync

# Install with specific optional dependencies
uv sync --extra dev
uv sync --extra ml

# Install all optional dependencies
uv sync --all-extras

Creating pyproject.toml manually

If you need to create a pyproject.toml file manually, here’s a template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "your-project-name"
version = "1.0.0"
description = "Your project description"
requires-python = ">=3.11"

dependencies = [
    "pandas~=2.3.1",
    "numpy~=2.3.1",
    "matplotlib~=3.10.3",
    "seaborn~=0.13.2",
    "plotly~=5.15.0",
    "scipy~=1.16.1",
]

[dependency-groups]
dev = [
    "ipykernel~=6.29.5",
    "jupyter~=1.1.1",
    "pytest~=8.4.1"
]

After creating this file, run:

1

uv sync --extra dev

Validation

Before proceeding to practical sessions, verify your setup:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# Test uv installation
uv --version

# Create test project
uv init test-project
cd test-project

# Add dependencies
uv add pandas numpy

# Test Python execution
uv run python -c "import pandas; print('✅ Setup successful!')"

# Check project structure
ls -la
cat pyproject.toml

# Clean up
cd ..
rm -rf test-project

Expected outputs:

• uv version displayed
• Project created successfully
• Dependencies installed quickly
• Python imports work correctly

Summary

You now have:

• ✅ Modern Python environment with uv
• ✅ Automatic virtual environment management
• ✅ Fast dependency installation and resolution
• ✅ Understanding of pyproject.toml configuration
• ✅ Simplified development workflow