Install & Compatibility
Where this runs
tested against v3.2.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.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 7.5s · import 1.108s · 240MB
243MB installed
● package 243MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
XGBClassifier
✓ from xgboost import XGBClassifier
XGBRegressor
✓ from xgboost import XGBRegressor
DMatrix
✓ from xgboost import DMatrix
train
✓ from xgboost import train
This quickstart demonstrates how to train a basic XGBoost classifier for a binary classification task using synthetic data. It showcases the common `XGBClassifier` API, similar to scikit-learn models.
import xgboost as xgb
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score
from sklearn.datasets import make_classification
import os
# 1. Generate synthetic data for a classification task
X, y = make_classification(n_samples=1000, n_features=20, n_informative=10, n_redundant=5, random_state=42)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
# 2. Initialize the XGBoost classifier
# 'objective' specifies the learning task.
# 'eval_metric' defines the metric for evaluation during training.
# `use_label_encoder=False` is recommended for XGBoost 1.x and 2.x to avoid a deprecation warning.
# `n_jobs` can be set to -1 to use all available CPU cores, or a specific number.
model = xgb.XGBClassifier(
objective='binary:logistic',
eval_metric='logloss',
n_estimators=100,
learning_rate=0.1,
max_depth=5,
use_label_encoder=False, # Required for older versions to silence warning
n_jobs=int(os.environ.get('XGB_N_JOBS', '-1')), # Example of using env var for N_JOBS
random_state=42
)
# 3. Train the model
model.fit(X_train, y_train)
# 4. Make predictions on the test set
y_pred = model.predict(X_test)
# 5. Evaluate the model's performance
accuracy = accuracy_score(y_test, y_pred)
print(f"Model Accuracy: {accuracy:.4f}")
xgboost --version
Debug
Known issues
breakingThe `output_margin` parameter for prediction was removed in XGBoost 2.0. Use `pred_contribs=True` or other specific output types if needed.fixRemove `output_margin` from prediction calls. Consult documentation for equivalent functionality if needed (e.g., `predict(output_margin=True)` for raw scores).
affects: >=2.0
breakingXGBoost 2.0 introduced significant changes to the model save/load format (`XGBoost.json` vs. older binary format) and the Python package structure. Models saved with older versions might not be directly loadable or usable with XGBoost 2.x without conversion.fixRetrain models with XGBoost 2.x if possible. For loading older models, consider converting them using utilities (if available) or retraining on the new version. Always save models using `model.save_model()` or `joblib.dump()` for compatibility.
affects: >=2.0
gotchaThe `xgboost-cpu` package version (e.g., 3.2.0) refers to a distribution/installer version, not the core `xgboost` library version it installs. As of `xgboost-cpu==3.2.0`, it installs `xgboost==2.0.3`. Always check `xgboost.__version__` after installation to confirm the underlying library version.fixRun `import xgboost; print(xgboost.__version__)` to verify the actual core library version installed. Be aware of documentation and API differences between the meta-package version and the core library version.
affects: All versions of `xgboost-cpu` and `xgboost-gpu` meta-packages
deprecatedThe `gpu_id` parameter for specifying GPU devices has been deprecated and replaced by the more general `device` parameter (e.g., `device='cuda:0'`, `device='cpu'`).fixReplace `gpu_id=0` with `device='cuda:0'` or similar in your model parameters. For CPU-only, `device='cpu'` can be explicitly set.
affects: 1.x, leading up to 2.x
gotchaFor optimal performance and memory efficiency with very large datasets, especially when using the raw C++ API via `xgboost.train` or `xgboost.cv` directly, it is highly recommended to use `xgboost.DMatrix` objects instead of raw NumPy arrays or Pandas DataFrames.fixConvert your data to `DMatrix` objects before passing to `xgboost.train` or `xgboost.cv`: `dtrain = xgb.DMatrix(X_train, label=y_train)`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'xgboost'
The `xgboost` library is not installed in the currently active Python environment, or the environment is not correctly activated.
fixEnsure you have installed the correct package using `pip install xgboost-cpu`. If using `conda`, use `conda install -c conda-forge xgboost`.
ValueError: feature_names mismatch
This commonly occurs when loading a pre-trained model and attempting to predict with a DataFrame that has different feature names or column order than the data used for training the model.
fixVerify that the feature names and their order in your prediction data match those used during training. Use `model.get_booster().feature_names` to inspect the expected names. If using `DMatrix`, ensure `feature_names` are passed correctly during its creation.
XGBoostError: DMatrix is not allowed to be empty
Attempting to create a `DMatrix` or train an XGBoost model with an empty dataset (e.g., input data with 0 rows or 0 columns, or all NaN values).
fixCheck your input data (features and labels) to ensure it is not empty, does not contain entirely null values, and has valid dimensions before passing it to `DMatrix` or the model's `fit` method.
TypeError: 'str' object cannot be interpreted as an integer
A parameter that expects an integer value (e.g., `n_jobs`, `num_boost_round`, `random_state`) was passed a string. This can happen when reading configuration from environment variables or text files without proper type conversion.
fixConvert the parameter value to an integer type. For example, use `n_jobs=int(os.environ.get('XGB_N_JOBS', '-1'))` or ensure direct assignments are `n_estimators=100` instead of `n_estimators='100'`. Upgrade
Version history
3.2.0latest on PyPI · released Feb 10, 2026
Audit
Dependencies
xgboost==2.0.3requiredThis meta-package installs the core XGBoost library at a specific version.
pythonrequiredRequired Python version.