Install & Compatibility
Where this runs
tested against v0.1.19 · 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 28.4s · import 0.000s · 1228.8MB
1146MB installed
● package 1146MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RayDMatrix
✓ from xgboost_ray import RayDMatrix
✗ from xgboost_ray import RayDMatrix
RayParams
✓ from xgboost_ray import RayParams
RayXGBClassifier
✓ from xgboost_ray import RayXGBClassifier
This quickstart demonstrates how to train a distributed XGBoost model using `xgboost-ray`. It initializes a local Ray cluster, loads a sample dataset, prepares it as a `RayDMatrix`, configures `RayParams` for distributed execution, and then calls `xgboost_ray.train`.
import ray
from xgboost_ray import RayDMatrix, RayParams, train
from sklearn.datasets import load_breast_cancer
import os
# Initialize Ray (if not already running)
if ray.is_initialized():
ray.shutdown()
ray.init(log_to_stdout=False) # log_to_stdout=False to suppress verbose Ray output in quickstart
# Load data
train_x, train_y = load_breast_cancer(return_X_y=True)
# Create RayDMatrix for distributed data handling
train_set = RayDMatrix(train_x, train_y)
# Configure Ray-specific training parameters
ray_params = RayParams(
num_actors=2,
cpus_per_actor=1
)
# Train the model using the xgboost-ray distributed train function
evals_result = {}
bst = train(
{
"objective": "binary:logistic",
"eval_metric": ["logloss", "error"],
},
train_set,
evals_result=evals_result,
evals=[(train_set, "train")],
verbose_eval=False,
ray_params=ray_params
)
print(f"Final training error: {evals_result['train']['error'][-1]:.4f}")
# Shutdown Ray cluster
ray.shutdown()
Debug
Known issues
breakingXGBoost-Ray v0.1.19 updated its API to work with XGBoost 2.0. This may introduce breaking changes if you are upgrading `xgboost-ray` and relying on specific API behaviors from older XGBoost versions.fixEnsure your `xgboost` version is compatible with `xgboost-ray` (typically XGBoost 2.0+ for recent `xgboost-ray` versions). Review XGBoost 2.0 release notes for core API changes.
affects: >=0.1.19
breakingXGBoost-Ray v0.1.12 introduced compatibility for `xgboost>=1.7.0`. Using `xgboost-ray` with `xgboost` versions older than 1.7.0 may lead to unexpected behavior or errors.fixUpgrade your `xgboost` package to version 1.7.0 or newer when using `xgboost-ray` versions 0.1.12 and above.
affects: <0.1.12
gotchaAlways use `xgboost_ray.RayDMatrix` instead of `xgboost.DMatrix` when passing data to `xgboost_ray.train`. `RayDMatrix` is essential for distributed data handling and sharding across Ray actors.fixChange your import and data matrix creation from `xgb.DMatrix(...)` to `RayDMatrix(...)`.
affects: All
gotchaExplicitly configure `num_actors` and `cpus_per_actor` in `RayParams`. While `xgboost-ray` attempts to auto-configure, manual specification is crucial for optimal performance, especially in heterogeneous clusters or multi-GPU setups. Ensure enough CPUs are available for Ray Data operations if used.fixSet `RayParams(num_actors=..., cpus_per_actor=...)` based on your cluster resources and workload. Consider reserving some CPU for Ray Data if performing heavy data operations.
affects: All
gotchaWhen using `RayDMatrix` with data sources that cannot be naturally sharded (e.g., a single large Parquet file), you may encounter a `RuntimeError` about insufficient shards. In such cases, enable centralized loading.fixPass `distributed=False` to `RayDMatrix` (e.g., `RayDMatrix(data, labels, distributed=False)`) to have the head node shard the data into the Ray object store.
affects: All
gotchaOn macOS, Ray's performance can degrade if the object store size exceeds 2.0GB. This may lead to warnings or slower execution for large datasets.fixEither specify `object_store_memory` in `ray.init()` to limit the size, or set the environment variable `RAY_ENABLE_MAC_LARGE_OBJECT_STORE=1` to ignore the warning (use with caution).
affects: All (macOS users)
Upgrade
Version history
0.1.19latest on PyPI · released Sep 20, 2023
Audit
Dependencies
xgboostrequiredCore machine learning library for gradient boosting. xgboost-ray acts as a distributed backend for it, with strong version coupling.
rayrequiredDistributed execution framework that xgboost-ray uses to scale training and prediction across clusters.
scikit-learnoptionalUsed in common examples for loading datasets; not a direct runtime dependency for core xgboost-ray functionality.