Install & Compatibility
Where this runs
tested against v2.8.1 · 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
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 17.5s · import 4.770s · 409MB
419MB installed
● package 419MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TargetEncoder
✓ from category_encoders import TargetEncoder
OneHotEncoder
✓ from category_encoders import OneHotEncoder
OrdinalEncoder
✓ from category_encoders import OrdinalEncoder
BinaryEncoder
✓ from category_encoders import BinaryEncoder
This example demonstrates how to use the `TargetEncoder` to convert categorical columns ('city', 'country') into numerical representations based on the 'target' variable. The `fit_transform` method is used on the training data, taking both features (X) and the target (y).
import pandas as pd
import category_encoders as ce
# Sample Data
data = {
'city': ['New York', 'London', 'Paris', 'New York', 'London', 'Berlin'],
'country': ['USA', 'UK', 'France', 'USA', 'UK', 'Germany'],
'target': [10, 20, 15, 12, 22, 18]
}
df = pd.DataFrame(data)
# Initialize and fit the TargetEncoder
# It's crucial to specify 'cols' to encode specific columns.
# For supervised encoders, 'y' is passed during fit_transform.
encoder = ce.TargetEncoder(cols=['city', 'country'])
encoded_df = encoder.fit_transform(df, df['target'])
print("Original DataFrame:")
print(df)
print("\nEncoded DataFrame:")
print(encoded_df)
Debug
Known issues
breakingBreaking changes in version 2.x removed support for older Python, pandas, and scikit-learn versions. Specifically, `category-encoders` v2.x requires Python >=3.11, pandas >=1.0, and dropped support for scikit-learn 0.x.fixEnsure your environment meets the minimum requirements: Python >=3.11, pandas >=1.0. If using scikit-learn, upgrade to a compatible version (e.g., >=1.0).
affects: >=2.0.0
breakingDefault parameters for some encoders, such as `TargetEncoder` (issue 327) and `HelmertEncoder` (`handle_missing`, `handle_unknown`), changed in minor 2.x releases. This can subtly alter encoding behavior compared to earlier versions.fixExplicitly set parameters like `handle_missing`, `handle_unknown`, or `smoothing` to match the desired behavior if migrating from an older version or to ensure consistent results.
affects: >=2.1.0, >=2.6.0
gotchaFor supervised encoders (e.g., `TargetEncoder`, `LeaveOneOutEncoder`), always use `fit_transform(X_train, y_train)` for training data and `transform(X_test)` for test data. Using `fit().transform()` on training data might lead to different results, as `fit_transform` often employs techniques like nested cross-validation to prevent overfitting during training.fixFollow the scikit-learn API pattern: `encoder.fit_transform(X_train, y_train)` and then `encoder.transform(X_test)`.
affects: All
gotchaHandling unknown categories in new data (e.g., in a production environment) can lead to errors or unexpected values. The `handle_unknown` parameter's default behavior varies by encoder; for `TargetEncoder`, it defaults to the target mean.fixConfigure `handle_unknown` (e.g., 'value', 'return_nan', or 'error') during encoder instantiation to explicitly define how unseen categories should be handled. For production, consider 'value' with a sensible default or 'return_nan' for error detection.
affects: All
gotchaIf the `cols` parameter is not provided during encoder instantiation, `category-encoders` will attempt to encode *all* non-numeric columns (object or pandas categorical dtype). This can unintentionally encode ID columns or numerical columns that were loaded as strings.fixAlways explicitly list the categorical columns to be encoded using the `cols` parameter to prevent accidental encoding of inappropriate features.
affects: All
gotchaUsing `OrdinalEncoder` for nominal (unordered) categorical variables can introduce an artificial, misleading order into the data, which may negatively impact models sensitive to numerical relationships (e.g., linear models).fixReserve `OrdinalEncoder` for genuinely ordinal data. For nominal variables, consider `OneHotEncoder`, `BinaryEncoder`, or other contrast encoders.
affects: All
gotchaInstalling `category-encoders` via `conda-forge` might provide an older version of the library (e.g., 1.x) that lacks recent features, bug fixes, or compatibility updates present in the latest pip release.fixIf you need the latest features and fixes, install via pip: `pip install category-encoders`. If using conda, check the available version carefully and consider creating a dedicated environment for pip installations if necessary.
affects: <=2.8.1 if installed via conda-forge
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'category_encoders'
The `category_encoders` library is not installed in the Python environment, or there's a typo in the import statement.
fixInstall the library using pip: `pip install category-encoders` or `conda install -c conda-forge category-encoders` if using Anaconda.
ValueError: Found unknown categories [...] in column [...] during transform
The encoder encountered categories in the test or new data that were not present in the training data it was fitted on. This error typically occurs when the `handle_unknown` parameter is set to 'error' (either explicitly in `category_encoders.OneHotEncoder` or if using scikit-learn's `OneHotEncoder` which defaults to 'error').
fixWhen initializing the encoder, set `handle_unknown='value'` (the default for `category-encoders.OneHotEncoder` which encodes unknown categories as all zeros) or `handle_unknown='indicator'` (adds a column to indicate unknown categories) to gracefully handle new categories. For example: `encoder = ce.OneHotEncoder(handle_unknown='value')`.
AttributeError: 'OrdinalEncoder' object has no attribute 'category_mapping'
This usually happens when attempting to access the `category_mapping` attribute on an `OrdinalEncoder` object, but the imported `OrdinalEncoder` is from `sklearn.preprocessing` instead of `category_encoders`, or an older version of `category-encoders` is being used where this attribute might not have existed or was named differently. The `category_encoders.OrdinalEncoder` does have a `category_mapping` attribute.
fixEnsure you are importing the `OrdinalEncoder` from `category_encoders`: `from category_encoders import OrdinalEncoder`. If the issue persists, verify your `category-encoders` version and upgrade if necessary: `pip install --upgrade category-encoders`.
KeyError: 'column_name'
This error occurs when the specified column in the `cols` parameter (or implicitly when `cols` is None) for an encoder is not found in the input DataFrame. It can also happen with specific encoders like `GLMMEncoder` if there's a mismatch in column handling.
fixDouble-check the column names passed to the encoder, especially when using the `cols` parameter, to ensure they exactly match the column names in your pandas DataFrame. Use `df.columns` to verify names and potential leading/trailing spaces. For `GLMMEncoder`, ensure the target column and features are correctly handled.
AttributeError: 'super' object has no attribute 'sklearn_tags'
This is a compatibility issue between `category-encoders` and newer versions of `scikit-learn`, where changes were made to the `sklearn_tags` attribute or its internal handling.
fixUpgrade your `category-encoders` library to the latest version, as this issue has been addressed in recent releases. Use `pip install --upgrade category-encoders`. If the problem persists, ensure your `scikit-learn` version is also compatible with the latest `category-encoders`.
Upgrade
Version history
2.10.0latest on PyPI · released Jul 26, 2026
Audit
Dependencies
numpyrequiredRequired for numerical operations.
statsmodelsrequiredRequired for statistical models used in some encoders.
scipyrequiredRequired for scientific computing functions.
pandasrequiredRequired for DataFrame input/output; version >= 1.0 recommended for full compatibility.