Getting Started with svy

Install svy and learn how its core objects fit together

Install svy and learn its object model: describe a survey Design, wrap your data in a Sample, then run design-based estimation and regression through simple accessors.

Keywords

install svy Python, svy getting started, svy Python tutorial, svy Design and Sample objects, design-based inference Python, survey weighting and estimation Python, stratified cluster sampling Python, Python survey analysis library, R survey package Python alternative

This page gets svy installed and gives you a mental model of the library: a small set of objects that compose the same way for every task. Once the model clicks, the tutorials are just deeper dives into each piece.

Installation

Install svy from PyPI using pip:

pip install svy

For enhanced output formatting and tables:

pip install "svy[report]"

For the fastest installation experience, use uv:

uv add "svy[report]"

System Requirements:

• Python 3.11, 3.12, 3.13, or 3.14
• Works on Linux, macOS, and Windows

For virtual-environment setup, uv projects, and troubleshooting, see the full Installation guide.

The svy Object Model

svy has a small, composable object model. Nearly every workflow follows the same three moves:

1. Describe the design with svy.Design(...) — how the sample was drawn.
2. Bind data and design into a svy.Sample(...) — the hub for everything.
3. Analyze through an accessor — sample.<accessor>.<method>().

import svy

# A small example survey bundled with svy (runs offline)
data = svy.datasets.load("hld_sample_wb_2023", source="bundled")

# 1. Describe the sampling design
design = svy.Design(
    stratum=("geo1", "urbrur"),  # stratification
    psu="ea",                    # primary sampling units (clusters)
    wgt="hhweight",              # survey weights
)

# 2. Bind data + design
sample = svy.Sample(data=data, design=design)

print(sample)

╭────────────── Sample ───────────────╮
│ Survey Data                         │
│   Rows     : 825                    │
│   Columns  : 19                     │
│   Strata   : 7                      │
│   PSUs     : 33                     │
│                                     │
│ Survey Design                       │
│   Row index          svy_row_index  │
│   Stratum            (geo1, urbrur) │
│   PSU                ea             │
│   SSU                None           │
│   Weight             hhweight       │
│   With replacement   False          │
│   Prob               None           │
│   Hit                None           │
│   MOS                None           │
│   Population size    None           │
│   Replicate weights  None           │
╰─────────────────────────────────────╯

Design accepts the pieces of any probability design — stratum, psu, ssu (second stage), wgt, fpc, and rep_weights for replicate-weight methods. Pass only what your design uses.

Everything hangs off the Sample

Once you have a sample i.e. sample=svy.Sample(...), each kind of task lives on its own accessor, so the call always reads sample.<accessor>.<method>():

Accessor	What it does	Learn more
sample.wrangling	Clean, recode, categorize, top/bottom-code, label	Wrangling
sample.sampling	Draw probability samples (SRS, systematic, PPS, multi-stage)	Selection
sample.weighting	Design weights, nonresponse adjustment, calibration	Weighting
sample.estimation	Means, totals, proportions, ratios, medians	Estimation
sample.categorical	Tabulation, cross-tabulation, tests	Categorical
sample.glm	Design-based regression (linear, logistic, Poisson)	GLM

For example, a design-based mean is sample.estimation.mean("pc_exp"), and a regression is sample.glm.fit(...) — see the Quick Start for both running end to end.

Planning a survey before you have data?

• Sample-size and power calculations have their own entry point, svy.SampleSize(...) — see Planning.
• Reading your own files uses svy.io (and the svy-io package for SPSS/Stata/SAS); the bundled example datasets above come from svy.datasets — see Datasets.

Ready to Explore?

Continue with hands-on tutorials covering real survey analysis workflows.

View Tutorials →