patsy

library1.0.2pypypi✓ verified 24d ago

Patsy is a Python package for describing statistical models and for building design matrices, bringing R-style formulas to Python. The current version is 1.0.2. While no new feature development is planned, it maintains a maintenance cadence to ensure compatibility with current releases in the Python ecosystem.

data

pip install patsy

github ↗package ↗

INSTALL

IMPORT

SIG · PATSY

patsy

datapythonv1.0.2

Install

3.8s avg

Import

265ms

Disk

91MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.260s · 90.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.8s · import 0.270s · 87MB

91MB installed

● package 91MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

dmatrix

✓ from patsy import dmatrix

dmatrices

✓ from patsy import dmatrices

demo_data

✓ from patsy import demo_data

A utility function for quick examples and testing.

This quickstart demonstrates how to use `patsy.dmatrices` to generate design matrices from a formula string and a dictionary-like data source. It automatically handles categorical variables and adds an intercept term.

import numpy as np from patsy import dmatrices, demo_data # Create example data data = demo_data("a", "b", "x1", "x2", "y") # Generate design matrices for a linear model y, X = dmatrices("y ~ x1 + x2 + a", data=data) print("Dependent variable (y):") print(y) print("\nIndependent variables (X):") print(X)

Debug

Known issues

breakingPython 2.7 support was dropped in version 1.0.0. Projects still on Python 2 must use an older version of Patsy.

fix

Upgrade to Python 3 or pin `patsy<1.0.0`.

affects: <1.0.0

gotchaPatsy automatically adds an intercept term and uses treatment coding for categorical variables (dropping one level). If you need to include all levels or omit the intercept, adjust your formula accordingly (e.g., `y ~ x1 + C(a) - 1` to remove intercept and explicitly code `a`).

fix

Use `- 1` in the formula to remove the intercept, or `C(variable, contr.treatment)` for explicit coding options.

affects: All

gotchaThe `NA_action='drop'` is the default for `dmatrix` and `dmatrices`, which means rows containing any missing values will be silently dropped. This can lead to unexpected data loss if not anticipated.

fix

Explicitly set `NA_action='raise'` to catch missing values or implement custom handling before calling Patsy functions.

affects: All

gotchaOperators like `**` in Patsy formulas are interpreted as interaction effects, not Python's power operator. Use `I()` (identity function) to force Python's interpretation (e.g., `I(x**2)`).

fix

Wrap expressions meant for literal Python evaluation in `I()`, like `I(x**2)`.

affects: All

gotchaPatsy fixed compatibility issues with `numpy >= 2` in version 1.0.0. Older versions might not work correctly with newer NumPy.

fix

Upgrade to `patsy>=1.0.0` if using `numpy>=2`.

affects: <1.0.0

gotchaPatsy fixed compatibility with Pandas 3's new `StringDtype` in version 1.0.2. Older versions may encounter issues with Pandas 3.

fix

Upgrade to `patsy>=1.0.2` if using `pandas>=3`.

affects: <1.0.2

deprecatedThe project is explicitly stated as 'no longer under active development' for new features, with 'Formulaic' identified as its spiritual successor. For new projects, considering Formulaic might be beneficial.

fix

Consider migrating to 'Formulaic' for new projects, while existing projects can continue to use Patsy for maintenance.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'patsy'

The `patsy` library is not installed in the Python environment where you are trying to use it, or the environment is not correctly activated.

fix

Install patsy using pip or conda: `pip install patsy` or `conda install patsy`.

patsy.PatsyError: Error evaluating factor: TypeError: 'int' object is not callable b ~ C(a)

This error occurs when a variable named `C` (or another built-in Patsy function name like `I` or `Q`) exists in your global or local Python namespace and conflicts with Patsy's attempt to use its own built-in `C()` function for categorical variables.

fix

Rename your conflicting variable (e.g., change `C = 1` to `my_C = 1`). Alternatively, for formula evaluation, you can explicitly pass `eval_env=0` (or a specific evaluation environment) to `patsy.dmatrix` or `statsmodels.formula.api.ols` to prevent local namespace lookups: `sm.ols('b ~ C(a)', data=df, eval_env=0).fit()`.

PatsyError: Error evaluating factor: NameError: no data named 'some_variable' found

The variable specified in the Patsy formula (e.g., 'some_variable') does not exist as a column in the DataFrame provided to `patsy.dmatrix` or `statsmodels.formula.api.ols`, or it contains invalid characters.

fix

Ensure that all variable names in your formula exactly match the column names in your DataFrame. If column names contain special characters (like '-', '+', ' '), rename them to be valid Python identifiers, or wrap them in `Q()` in the formula (e.g., `Q('CFC-11')`).

PatsyError: Number of rows mismatch between data argument and column (statsmodels)

There is an inconsistency in the number of rows between the outcome variable and the predictor variables, often caused by missing values (`NaN`) in the data which Patsy handles by dropping entire rows by default, or an issue with the indexing of the input data.

fix

Inspect your DataFrame for missing values (`df.isnull().sum()`) in the columns used in the formula. Patsy drops rows with NaNs by default. Ensure your data is clean and aligned before passing it to Patsy, or explicitly handle missing values (e.g., imputation or dropping them manually before calling Patsy).

Upgrade

Version history

1.0.2latest on PyPI · released Oct 20, 2025

Audit

Dependencies

numpyrequiredCore dependency for numerical operations and design matrix representation.

pandasoptionalCommonly used for data input/output and data structures, though not a hard dependency for basic functionality.

scipyoptionalRequired for spline-related functions like `bs`.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/pydata/patsy ↗

packagehttps://pypi.org/project/patsy/ ↗