Install & Compatibility
Where this runs
tested against v0.12.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 2.327s · 232.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.4s · import 2.176s · 224MB
234MB installed
● package 234MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LinearGAM
✓ from pygam import LinearGAM
Primary class for fitting Linear Generalized Additive Models
LogisticGAM
✓ from pygam import LogisticGAM
Primary class for fitting Logistic Generalized Additive Models
PoissonGAM
✓ from pygam import PoissonGAM
Primary class for fitting Poisson Generalized Additive Models
s
✓ from pygam import s
Helper function to define a spline term for a feature
f
✓ from pygam import f
Helper function to define a factor term for a categorical feature
te
✓ from pygam import te
Helper function to define a tensor product interaction term
This quickstart demonstrates how to install pyGAM, load an example dataset, define a LinearGAM with spline and factor terms, fit the model to the data, and then print a statistical summary. It also includes a basic prediction example.
import numpy as np
from pygam import LinearGAM, s, f
from pygam.datasets import wage
X, y = wage() # Load example data
# Define a GAM with a spline term for features 0 and 1, and a factor term for feature 2
gam = LinearGAM(s(0) + s(1) + f(2))
# Fit the model
gam.fit(X, y)
# Print a summary of the model fit
print(gam.summary())
# Example of predicting (using dummy data for simplicity)
dummy_X = np.array([[10, 20, 1], [15, 25, 0]])
predictions = gam.predict(dummy_X)
print(f"Predictions for dummy data: {predictions}")
Debug
Known issues
gotchaInstalling NumPy/SciPy linked to Intel MKL for acceleration can be tricky, especially with Conda due to channel compatibility issues. Pip's NumPy-MKL is often outdated. Consider third-party builds or specific Conda channels if MKL optimization is critical.fixFor MKL acceleration, explicitly search for and install NumPy/SciPy with MKL via specific Conda channels (e.g., intel channel) or use third-party builds (e.g., `pip install numpy scipy --extra-index-url https://urob.github.io/numpy-mkl`).
affects: All versions
gotchaP-values derived from models where smoothing parameters have been estimated may be lower than they should be, leading to an increased rate of false positives (rejecting the null hypothesis too readily).fixInterpret p-values with caution, especially when smoothing parameters are estimated. Consider alternative model evaluation metrics or sensitivity analyses.
affects: All versions
gotchaWhen combining a spline term (e.g., `s(feature)`) and a linear term for the *same* feature in a GAM, it can introduce a model identifiability problem. This can cause p-values to appear statistically significant when they are not.fixAvoid including both a spline and a linear term for the same feature in a single GAM specification. Use either `s()` for a flexible non-linear effect or `l()` for a purely linear effect.
affects: All versions
gotchaThe `pyGAM` package available on `conda-forge` is typically less up-to-date than the version available via `pip`.fixFor the most current features and bug fixes, prioritize installing `pygam` using `pip`.
affects: All versions
gotchaFor large models with constraints, installing `scikit-sparse` can significantly improve optimization performance due to its faster sparse Cholesky factorization. It also has a dependency on `nose` for its import.fixIf working with large or constrained models, install `scikit-sparse` and `nose`: `conda install -c conda-forge scikit-sparse nose` (or equivalent pip install if available).
affects: All versions
gotchapyGAM is officially tested with Python 3.10+ and is compatible up to Python 3.13. Using it with significantly older or very new, untested Python versions might lead to unexpected compatibility issues.fixEnsure your Python environment is within the supported range (3.10 to 3.13) for optimal compatibility.
affects: Python versions outside 3.10-3.13
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pygam'
The `pygam` library is not installed in the Python environment being used, or the Python interpreter configured in the IDE/terminal does not have access to the installed `pygam` package. This is a common issue when multiple Python versions or virtual environments are present.
fixEnsure `pygam` is installed in the active Python environment: `pip install pygam`. If using an IDE like VS Code or PyCharm, verify that the correct Python interpreter where `pygam` is installed is selected.
numpy.linalg.LinAlgError: Singular matrix
This error often arises in `pygam` due to numerical instability in underlying NumPy/SciPy operations, particularly when dealing with newer versions of these libraries or ill-conditioned data, which can lead to problems with matrix inversions or QR decompositions during model fitting.
fixOne common fix involves ensuring compatibility with newer NumPy/SciPy versions by converting sparse matrices to dense arrays before certain linear algebra operations, for example: `Q, R = np.linalg.qr(WB.toarray())` (referencing a known fix for `pygam/pygam.py` and `pygam/utils.py`).
ValueError: X data is out of domain for categorical feature
This error typically occurs when using `pygam.partial_dependence` with categorical features that do not include '0' as one of their encoded categories. `pyGAM`'s internal `partial_dependence` function might expect categorical features to be represented with a '0' label, causing an 'out of domain' error when it encounters other values.
fixTransform your categorical features so that one of the categories (often the first one) is encoded as `0`. A workaround could involve subtracting the minimum value from each categorical feature to shift its range to start from zero.
ImportError: cannot import name 's' (or 'f')
This `ImportError` usually indicates that the `pygam` installation is outdated or corrupted, especially if installed via `conda-forge` which might lag behind `pip` releases. The `s()` (for spline terms) and `f()` (for factor terms) functions are fundamental to defining `pygam` models.
fixUpgrade `pygam` to the latest version using pip: `pip install --upgrade pygam`. If using conda, consider switching to pip for `pygam` if the conda package is not up-to-date: `pip install pygam`.
Upgrade
Version history
0.12.0latest on PyPI · released Dec 18, 2025
Audit
Dependencies
numpyrequiredCore numerical operations
scipyrequiredCore numerical operations
progressbar2requiredProgress bar for model fitting
pandasoptionalRequired by pygam.datasets submodule for data loading
scikit-sparseoptionalCan significantly speed up optimization on large models with constraints by providing a faster sparse Cholesky factorization