Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
Who this is for: researchers and analysts who have categorical columns (sex, site, treatment arm, instrument) and need to turn them into numeric columns for a scikit-learn model. After reading you should be able to fit OneHotEncoder, choose handle_unknown and drop deliberately, read the output columns, and fix the common errors. Documentation checked: scikit-learn 1.9.1, read 2026-11-11.
sklearn.preprocessing.OneHotEncoder encodes each categorical feature as one binary column per category. A row gets 1 in the column for its own category and 0 in the others. By default it returns a SciPy sparse matrix, and it raises an error if transform meets a category it did not see during fit.
What it is used for in research
Most scikit-learn estimators expect numeric input. A nominal variable such as “site” has no order, so coding it as 1, 2, 3 would imply a ranking the data does not have. One-hot encoding avoids that by giving each category its own indicator column. The same transformation is called dummy coding in statistics; dropping a column is covered under the drop parameter below. Encoders are fitted on training data only, which ties into cross-validation and the risk of overfitting.
onehotencoder sklearn: the correct import
People search both word orders; the class is the same. The import path is sklearn.preprocessing.OneHotEncoder, not sklearn.OneHotEncoder:
from sklearn.preprocessing import OneHotEncoder
How to install or access it
The scikit-learn installation page (scikit-learn.org/stable/install.html) gives these commands. In a virtual environment:
python -m venv sklearn-envsource sklearn-env/bin/activate(on Windows:sklearn-envScriptsactivate)pip install -U scikit-learn
With conda: conda create -n sklearn-env -c conda-forge scikit-learn, then conda activate sklearn-env. The documented minimum dependencies are NumPy 1.24.1, SciPy 1.10.0, joblib 1.4.0 and threadpoolctl 3.5.0.
Step-by-step task: encode categorical columns
The signature in the 1.9.1 documentation is:
OneHotEncoder(*, categories='auto', drop=None, sparse_output=True, dtype=np.float64, handle_unknown='error', min_frequency=None, max_categories=None, feature_name_combiner='concat')
- Import the class:
from sklearn.preprocessing import OneHotEncoder. - Create the encoder, choosing
handle_unknown(anddropif needed):enc = OneHotEncoder(handle_unknown='ignore'). - Fit it on training data only:
enc.fit(X_train). Categories are learned per column and stored inenc.categories_. - Transform data with
enc.transform(X). By default the result is a sparse CSR matrix; call.toarray(), or create the encoder withsparse_output=False, for a dense array. - Recover column names with
enc.get_feature_names_out(['gender','group']).
Worked example from the official documentation
X = [['Male', 1], ['Female', 3], ['Female', 2]]
enc = OneHotEncoder(handle_unknown='ignore').fit(X)
enc.categories_
# [array(['Female', 'Male'], dtype=object), array([1, 2, 3], dtype=object)]
enc.transform([['Female', 1], ['Male', 4]]).toarray()
# array([[1., 0., 1., 0., 0.],
# [0., 1., 0., 0., 0.]])
enc.inverse_transform([[0, 1, 1, 0, 0], [0, 0, 0, 1, 0]])
# array([['Male', 1], [None, 2]], dtype=object)
enc.get_feature_names_out(['gender', 'group'])
# ['gender_Female', 'gender_Male', 'group_1', 'group_2', 'group_3']
The second input row contains group 4, which was never seen in fit. Because handle_unknown='ignore', its group columns are all zeros instead of raising an error.
Using it on only some columns
ColumnTransformer applies the encoder to chosen columns. Its signature is ColumnTransformer(transformers, *, remainder='drop', sparse_threshold=0.3, n_jobs=None, transformer_weights=None, verbose=False, verbose_feature_names_out=True). Note that remainder='drop' is the default, so columns you do not list are discarded unless you set remainder='passthrough'. With verbose_feature_names_out=True, output names are prefixed “{transformer_name}__{feature_name}”. With sparse_threshold=0 the output is always dense. The pattern is described in the scikit-learn user guide section on encoding categorical features; the model examples in scikit-learn logistic regression and scikit-learn random forest take such encoded matrices as input.
Output and how to read it
Each input column becomes one output column per learned category, in the order of categories_ (sorted for the example above: Female before Male). Rows are the original samples; a single 1 per original feature marks the category. Useful attributes after fitting: categories_, drop_idx_, infrequent_categories_, n_features_in_ and feature_names_in_. Methods: fit, transform, fit_transform, inverse_transform, get_feature_names_out and set_output.
Parameters and the version each arrived in
| Parameter | Added or changed | What it does |
|---|---|---|
categories |
0.20 | ‘auto’ learns categories from the data, or you pass an explicit list per feature |
drop |
0.21 | None, ‘first’, ‘if_binary’, or an array specifying which category to drop per feature |
min_frequency, max_categories |
1.1 | Group rare categories into one infrequent column |
sparse_output |
1.2 (renamed from sparse) |
True returns a sparse matrix, False a dense array |
feature_name_combiner |
1.3 | Controls how output column names are built; default ‘concat’ |
handle_unknown='warn' |
1.6 | Added as an option for handle_unknown |
If older tutorial code uses sparse=False, replace it with sparse_output=False.
handle_unknown and inverse_transform
| handle_unknown | Unknown category at transform | inverse_transform of an all-zero block |
|---|---|---|
| ‘error’ (default) | Raises an error | Not applicable |
| ‘ignore’ | All zeros for that feature | None |
| ‘infrequent_if_exist’ | Mapped to the infrequent column if one exists, otherwise treated like ‘ignore’ | ‘infrequent_sklearn’ for the infrequent column |
Choosing drop
drop='first' removes the first category of each feature, and drop='if_binary' drops one column only for two-category features. On the example data, drop='first' gives [[0,0,0],[1,1,0]] for [['Female',1],['Male',2]], and drop='if_binary' gives [[0,1,0,0],[1,0,1,0]]. The documentation says dropping is useful to avoid collinearity, for example with an unregularized linear regression, but warns that it “breaks the symmetry of the original representation and can therefore induce a bias in downstream models, for instance for penalized linear classification or regression models.” Keep all columns for penalized models; consider dropping for unpenalized ones.
Rare categories
An integer min_frequency is a count threshold; a float is a fraction of n_samples. max_categories counts the infrequent group itself, and min_frequency is applied before max_categories. Documentation example: with X = ["a"]*5 + ["b"]*20 + ["c"]*10 + ["d"]*3 (as a column) and OneHotEncoder(max_categories=3, sparse_output=False), infrequent_categories_ is [['a','d']] and transforming “a” and “b” gives [[0,0,1],[1,0,0]]: the infrequent column is last.
Troubleshooting
Error: found unknown categories during transform
This is the default handle_unknown='error' behaviour. A category appeared in test or new data that the training data lacked. Either set handle_unknown='ignore' (or ‘infrequent_if_exist’), or pass an explicit categories list. Fit only on training data, then reuse the fitted encoder for the test set; refitting on the test set produces a different column layout.
Mixed strings and numbers in one feature
The documentation says not to mix strings and numbers within one feature. Convert the column to a single type first.
Output is a sparse matrix and a downstream step needs an array
Use .toarray() or sparse_output=False. Large numbers of categories make dense output memory-heavy, which is why sparse is the default.
Unexpected missing columns after ColumnTransformer
Check remainder; the default drops unlisted columns.
Old code uses the sparse argument
The argument was renamed sparse_output in 1.2; update the call.
Free alternatives
scikit-learn is itself free and open source. Within the same package, OrdinalEncoder produces integer codes instead of indicator columns and is appropriate only when categories have a natural order.
| Tool | Notes |
|---|---|
sklearn.preprocessing.OrdinalEncoder |
Free, same package. Gives one integer-code column per feature (0 to n_categories – 1) instead of indicator columns. handle_unknown='use_encoded_value' with unknown_value sets a code for unseen categories. Suitable only when categories have a natural order. |
pandas.get_dummies |
Free. Returns one 0/1 column per distinct value, with the original column name prepended. Options include columns, drop_first, dummy_na, sparse and dtype. It works on the data you pass in, so it does not store categories learned from training data the way a fitted encoder does. |
FAQ
What does sklearn OneHotEncoder do?
It converts each categorical column into one binary column per category so numeric models can use it; the default output is sparse.
How do I get a dense array instead of a sparse matrix?
Set sparse_output=False or call .toarray() on the result.
How do I handle categories that appear only in new data?
Set handle_unknown='ignore'; the row gets zeros for that feature.
Should I use drop=’first’?
It avoids collinearity for unregularized linear models, but the documentation warns it can bias penalized models. Keep all columns for those.
What is the import path?
from sklearn.preprocessing import OneHotEncoder.







