Model selection
Compare a finite set of model hyperparameters using a consistent cross-validation protocol.
Scikit-Learn · Class
GridSearchCV
GridSearchCV exhaustively evaluates estimator hyperparameter combinations from a parameter grid using cross-validation. After fitting, it retains the best configuration and can delegate supported estimator methods.
How it works
GridSearchCV evaluates every combination described by param_grid using cross-validation and the selected scoring strategy. After fitting, it retains the best configuration and delegates estimator operations such as prediction when the underlying estimator supports them.
Syntax
class sklearn.model_selection.GridSearchCV(estimator, param_grid, *, scoring=None, n_jobs=None, refit=True, cv=None, verbose=0, pre_dispatch='2*n_jobs', error_score=nan, return_train_score=False)Parameters
| Name | Type | Description |
|---|---|---|
estimator | estimator | Estimator object implementing the estimator interface; its parameters are optimized. |
param_grid | dict or list of dictionaries | Dictionary mapping parameter names to candidate lists, or a list of such dictionaries. |
scoring | str, callable, list, tuple or dict, default=None | Evaluation strategy for the cross-validated model; defaults to the estimator's score method. |
n_jobs | int, default=None | Number of jobs run in parallel; None means one job unless a backend changes that behavior. |
refit | bool or str, default=True | Whether to refit the estimator using the selected parameters; default True. |
cv | int, cross-validation generator or iterable, default=None | Cross-validation splitter or integer fold count; default None. |
verbose | int, default=0 | Verbosity level. |
pre_dispatch | int or str, default='2*n_jobs' | Number of jobs dispatched during parallel execution; default '2*n_jobs'. |
error_score | number or 'raise', default=nan | Value assigned when a fitting failure occurs; default nan. |
return_train_score | bool, default=False | Whether to include training scores in cv_results_; default False. |
Returns
A fitted GridSearchCV object exposing the selected estimator configuration and cross-validation results, including attributes such as best_params_, best_score_, best_estimator_, and cv_results_.
Key points
- It tests every combination formed by the supplied parameter values rather than sampling only some candidates.
- The object follows the estimator interface, including fitting and scoring.
- Cross-validation selects estimator parameters according to the configured grid and evaluation strategy.
- param_grid maps estimator parameter names to candidate values.
- scoring specifies how validation performance is measured.
- Fitting performs the search, while prediction is available as a primary fitted-object operation.
Common mistakes
- If scoring is omitted, the estimator must implement score; otherwise provide scoring explicitly.
- A list of parameter dictionaries represents separate grids, and every combination in each grid is searched.
Example: Exhaustive SVC parameter search
from sklearn.datasets import load_iris
from sklearn.model_selection import GridSearchCV
from sklearn.svm import SVC
X, y = load_iris(return_X_y=True)
search = GridSearchCV(
SVC(),
{"C": [0.1, 1, 10], "kernel": ["linear", "rbf"]},
cv=5,
scoring="accuracy",
)
search.fit(X, y)
print(search.best_params_)
print(search.best_score_)Evaluates every listed SVC parameter combination with five-fold cross-validation, then exposes the best configuration and its mean validation score.
When to use it
Pipeline tuning
Optimize a pipeline's preprocessing and estimator settings together by naming nested parameters in the grid.
Custom evaluation
Evaluate several scoring criteria or choose a domain-specific callable for validation.
Interview questions
QHow does GridSearchCV choose hyperparameters?
It exhaustively evaluates all combinations in param_grid with cross-validation. After fitting, the best combination is retained and exposed through the fitted search object.
Follow-up: How would you search continuous values more flexibly? Use RandomizedSearchCV with a distribution, or refine a discretized grid around promising values.
QWhat is the role of scoring?
scoring controls how each cross-validated test result is evaluated. If scoring is None, the wrapped estimator must provide a score method.
Follow-up: What happens when an estimator has no score method? Pass an explicit scoring strategy, such as a metric name or callable.
QWhich estimator operations can the fitted object provide?
The class supports fit and score, and can also expose methods such as predict, predict_proba, decision_function, transform, and inverse_transform when the wrapped estimator implements them.
Follow-up: Does fitting the search object alter the original estimator instance? The search clones and fits estimator configurations internally, so use the fitted search object's delegated methods and attributes.
Related
RandomizedSearchCVParameterGridcheck_scoringcross_validate