Install & Compatibility
Where this runs
tested against v1.2.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.178s · 312.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 12.6s · import 2.052s · 300MB
312MB installed
● package 312MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Formula
✓ from formulaic import Formula
Use this for explicit formula object creation, allowing for inspection and reuse of the model specification.
model_matrix
✓ from formulaic import model_matrix
A convenience function for one-off model matrix generation.
This example demonstrates how to create design matrices using Wilkinson formulas from a pandas DataFrame. It shows both the explicit `Formula` class approach and the `model_matrix` shorthand function.
import pandas
from formulaic import Formula, model_matrix
df = pandas.DataFrame({
'y': [0, 1, 2],
'x': ['A', 'B', 'C'],
'z': [0.3, 0.1, 0.2],
})
print("Using Formula class (recommended for advanced use/reuse):")
f = Formula('y ~ x + z')
y_formula, X_formula = f.get_model_matrix(df)
print("Response (y) from Formula:\n", y_formula)
print("Design Matrix (X) from Formula:\n", X_formula)
print("\nUsing model_matrix shorthand:")
y_short, X_short = model_matrix('y ~ x + z', df)
print("Response (y) from model_matrix:\n", y_short)
print("Design Matrix (X) from model_matrix:\n", X_short)
Debug
Known issues
gotchaFormulaic, following Wilkinson formula conventions, automatically adds an intercept term (unless explicitly removed) and typically uses treatment coding for categorical variables by default. This might differ from expectations if coming from other statistical packages or manual feature engineering methods.fixTo remove the intercept, use `y ~ -1 + x + z`. To specify different contrasts, refer to the official documentation on 'Contrasts'.
affects: All 1.x.x versions
gotchaWhile `model_matrix` provides a convenient shorthand, direct use of `Formula('...').get_model_matrix()` is recommended for scenarios where you need to inspect the compiled formula structure, or reuse the generated `ModelSpec` to ensure consistent transformations across multiple datasets (e.g., training and testing data).fixFor complex workflows or production, prefer `f = Formula('...'); y, X = f.get_model_matrix(df)` and save/reuse `f` or its underlying `ModelSpec`. affects: All 1.x.x versions
gotchaFormulaic is optimized for working with tabular data, most commonly `pandas.DataFrame` for input. While it supports other data structures (NumPy arrays, SciPy sparse matrices, Narwhals dataframes), inconsistencies in input formats or unexpected data types within columns can lead to errors.fixEnsure input data is a `pandas.DataFrame` where possible, and column data types are appropriate for the desired transformations (e.g., numeric for arithmetic operations, string/category for categorical encoding).
affects: All 1.x.x versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'formulaic'
The `formulaic` library is not installed in the Python environment, or the Python interpreter cannot find it in the configured paths.
fixInstall the library using pip: `pip install formulaic`
KeyError: 'column_name'
A formula or code attempts to access a column in a pandas DataFrame (or a key in a dictionary) that does not exist in the provided data.
fixEnsure that all variables referenced in your formula or code exist as column names in your input DataFrame, checking for typos and case sensitivity. For example, if 'column_name' is missing, add it to your DataFrame or correct the reference.
PatsyError: Error evaluating factor: NameError: name '...' is not defined
This error occurs when the formula string contains invalid Python syntax or refers to variable names that are not valid Python identifiers (e.g., containing special characters like '%' or '*' which are interpreted as operators by Patsy, the underlying formula parsing library used by Formulaic) without proper quoting.
fixQuote variable names containing special characters using `Q('variable name')` within the formula string. For example, change `y ~ %White` to `y ~ Q('%White')`. Also, wrap arithmetic expressions within `I()` to force Python evaluation, e.g., `y ~ I(x*10)`. ValueError: The formula sets the intercept to False, contradicting fit_intercept=True.
This specific error arises when using `formulaic` (often indirectly through a statistical modeling library) where the formula explicitly removes the intercept (e.g., using `y ~ 0 + x`) but the model fitting function is configured to automatically fit an intercept (`fit_intercept=True`). This creates a conflict in how the intercept should be handled.
fixEither remove the explicit intercept removal from the formula (e.g., `y ~ x`) or set the `fit_intercept` parameter in your model fitting function to `False` (e.g., `model(..., fit_intercept=False)`).
Upgrade
Version history
1.2.2latest on PyPI · released Jun 2, 2026
Audit
Dependencies
pandasoptionalCommonly used for input dataframes and highly integrated into examples.
numpyoptionalUsed for numerical operations and an output format option.
scipyoptionalUsed for sparse matrix output option.