Installation Guide

Default Setup

To use svy, you first need to install it. You can install svy using pip:

pip install svy

If you want to add additional packages to improve the presentation and reporting of the results, you can add the report option as follows

pip install "svy[report]"

We recommend using a virtual environment to install svy. You can create one with:

python -m venv venv

You can replace venv with any name you prefer, e.g. .venv or svy_env. Activate the virtual environment with:

source venv/bin/activate

Recommended Setup for the Tutorials

For the tutorials, we will use the uv package manager to create and configure a new Python project. If you prefer a different Python package manager (e.g., venv, pipx, poetry, or pipenv), feel free to use that instead.

Step 1: Install uv

You may skip this step if you already have uv installed.

pip install uv

For best results, install uv globally so it’s available across all your projects. Refer to the official installation guide for platform-specific instructions.

Step 2: Create a Project Folder

Navigate to the directory where you would like to create your project and run:

mkdir my_project
cd svy_tutorial
uv init

Alternatively, create and initialize the project in one step:

uv init svy_tutorial

This generates the following structure:

svy_tutorial/
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

.python-version → Python version for the virtual environment
pyproject.toml → project configuration and dependencies
main.py → placeholder script
README.md → project overview

Step 3: Add svy as a Dependency

Use uv add to add the svy package:

uv add "svy[report]"

This adds svy under [project] dependencies in your pyproject.toml and installs it:

[project]
name = "svy_tutorial"
dependencies = ["svy[report]"]

If you want to pin a specific version:

uv add "svy[report]==0.1.0"

Add additional packages:

uv add pandas
uv add ruff --dev

Remove a package:

uv remove pandas

Upgrade a package:

uv lock --upgrade-package svy

Next Steps

Next, take a quick tour of Sample—the main abstraction for working with a survey sample: Quick Tour.