Installation Guide

Complete installation instructions for svy Python package. Install via pip or uv with optional dependencies for reporting and analysis.

Keywords

svy installation, install svy Python, pip install svy, uv package manager, Python survey package setup

Get svy installed and ready for the tutorials. Choose the method that fits your workflow.

Quick Install (Recommended)

Install svy with pip:

pip install "svy[report]"

This includes the core package plus enhanced output formatting.

That’s it! You’re ready for the tutorials.

---

Installation Methods

Standard Installation

Core functionality only:

pip install svy

Includes: Sample design, weighting, variance estimation, and statistical analysis.

With Reporting Features

Enhanced output and tables (recommended for tutorials):

pip install "svy[report]"

Adds: Rich console output and publication-ready tables via great-tables.

---

Using Virtual Environments

Always use a virtual environment to avoid dependency conflicts.

Option 1: venv (Built-in)

# Create virtual environment
python -m venv .venv

# Activate on macOS/Linux
source .venv/bin/activate

# Activate on Windows
.venv\Scripts\activate

# Install svy
pip install "svy[report]"

Option 2: uv (Recommended)

uv is a fast, modern Python package manager perfect for following along with tutorials.

Visit https://docs.astral.sh/uv/ to download uv for your platform.

Create Tutorial Project

# Create and initialize project
uv init svy_tutorial
cd svy_tutorial

# Add svy with reporting features
uv add "svy[report]"

This creates:

svy_tutorial/
├── .python-version    # Python version (auto-detected)
├── pyproject.toml     # Project config and dependencies
├── uv.lock           # Locked dependency versions
├── main.py           # Your analysis script
└── README.md

Your pyproject.toml:

[project]
name = "svy_tutorial"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "svy[report]"
]

Working with uv

# Add packages as you go
uv add numpy polars

# Add development tools
uv add pytest ruff --dev

# Run Python scripts
uv run python main.py

# Start Jupyter (if needed)
uv add jupyter --dev
uv run jupyter lab

# Upgrade svy
uv lock --upgrade-package svy

# Sync environment
uv sync

Why uv for tutorials?

• ⚡ Fast - 10-100x faster than pip
• 🔒 Reproducible - Exact versions locked
• 🎯 Simple - Easy dependency management
• 📦 Self-contained - Everything in one project folder

---

Verify Installation

Confirm svy is working:

# Check version
python -c "import svy; print(svy.__version__)"

Expected output: 0.2.0 (or current version)

---

System Requirements

Python Version:

• Python 3.11, 3.12, or 3.13 required
• Python 3.10 and 3.14 not currently supported

Operating Systems:

• ✅ Linux
• ✅ macOS
• ✅ Windows

Key Dependencies (auto-installed):

• NumPy
• Polars[pyarrow]
• SciPy

---

Troubleshooting

“No module named ‘svy’”

Package not installed in active environment:

# Check which Python
which python

# Install in correct environment
pip install "svy[report]"

Import errors for optional features

Missing optional dependencies:

# Install reporting features
pip install "svy[report]"

NumPy/SciPy compilation errors

Update pip and try again:

pip install --upgrade pip
pip install "svy[report]"

uv not found after installation

Restart your terminal or add to PATH:

# Check installation
uv --version

# If not found, follow platform-specific PATH instructions at:
# https://docs.astral.sh/uv/

---

Tutorial-Specific Setup

For these tutorials, we recommend:

# Create tutorial project with uv
uv init svy_tutorial
cd svy_tutorial

# Install svy with reporting
uv add "svy[report]"

# Add packages used in tutorials
uv add polars pandas

# Optional: Jupyter for interactive work
uv add jupyter --dev

All tutorial code examples assume this setup.

---

Getting Help

Installation issues?

• 💬 Ask on GitHub Discussions
• 🐛 Report bugs on GitHub Issues
• 📧 Email info@svylab.com

---

Next Steps

Now that svy is installed, take a quick tour of the core concepts:

→ Quick Tour - Learn the Sample object and basic workflow in 5 minutes

---

Ready to start?
Continue to the Quick Tour →