Installation Guide for svy

pip, uv, virtual environments, and troubleshooting

Complete installation instructions for the svy Python package. Install via pip or uv with optional dependencies for reporting, small area estimation, and survey analysis.

Keywords

Python survey analysis package, install survey sampling Python, pip install survey package, Python survey statistics library, uv package manager Python, Python virtual environment survey, survey analysis Python setup, Python 3.11 3.12 3.13 3.14 survey, complex survey Python dependencies, survey package troubleshooting Python

svy is a standard Python package, so you can install it with whatever tool you already use — uv, pixi, pip, Poetry, or conda. These tutorials use uv (fast, reproducible, and self-contained), so commands are shown with uv, with the pip equivalent alongside.

Quick Install

uv add "svy[report]"          # used throughout these tutorials
# or with pip:
pip install "svy[report]"

This installs the core package plus rich console output. That’s it — you’re ready for the tutorials.

uv add runs inside a uv project. If you don’t have one yet, the next section sets one up in seconds; with pip, install into a virtual environment.

What to Install

svy’s core has everything for analysis; two optional extras add to it.

Core only

uv add svy                    # or: pip install svy

Includes: sample design, weighting, variance estimation, and statistical analysis, plus the example datasets packaged with svy. A core install makes no network calls.

With reporting (recommended)

uv add "svy[report]"          # or: pip install "svy[report]"

Adds: rich console output. The tutorials assume this.

With the online dataset catalog

uv add "svy[remote]"          # or: pip install "svy[remote]"

Adds: downloads of the full example datasets from the svyLab catalog (see Datasets). svy[all] installs both extras.

Using Virtual Environments

Always work in a virtual environment to avoid dependency conflicts.

Option 1: uv (recommended)

uv is a fast, modern Python package manager that also manages the virtual environment for you — uv add creates and uses one automatically, so there’s nothing extra to activate.

Visit https://docs.astral.sh/uv/ to download uv for your platform, then create a project:

# Create and initialize a 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

Option 2: venv (built-in)

Prefer the standard library? Create and activate a virtual environment, then install with pip:

# 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]"

Verify Installation

Confirm svy is working:

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

0.31.0

System Requirements

Python Version:

• Python 3.11, 3.12, 3.13, or 3.14 required

Operating Systems:

• ✅ Linux
• ✅ macOS
• ✅ Windows

Key Dependencies (auto-installed):

• NumPy
• Polars[pyarrow]
• SciPy
• msgspec
• svy-rs
• svy-io

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

The tutorials use svy’s rich, pretty-printed output, so install the reporting extra (this is what the examples assume):

uv add "svy[report]"        # or: pip install "svy[report]"

Plain svy works too if you prefer a lighter environment — you’ll just get simpler text output instead of formatted tables.

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 →