Parameters

This page lists every training knob, with its type, default, and effect on the model. Set any parameter three ways: on the CLI with --set tree.max_depth=8, under [tree] in a TOML config, or in Python with params=[("tree.max_depth", 8)]. Run bonsai params to print the whole default config as TOML.

The table below is generated from docs/use/parameters.src.json, extracted from the default Config by make params-json (which runs bonsai params). CI checks the page against that JSON. Re-run make params-json after adding or renaming a knob so the extraction tracks the structs.

dispatch

Selects the algorithm: which loss, which tree grower, which row sampler.

parameter	type	default	effect
grower_name	string	"depthwise"	Tree-growth strategy: depthwise, leafwise, or oblivious (plus cuda_ variants). Leafwise cuts loss faster per node; oblivious builds symmetric trees.
objective_name	string	"mse"	Training loss: mse, mae, huber, quantile, poisson, logloss, or softmax. Sets the gradients, the link, and the default metrics.
sampler_name	string	"all_rows"	Row-sampling strategy: all_rows, bernoulli (uniform subsample), or goss (keeps large-gradient rows). Trades a little accuracy for training speed.

booster

The boosting loop: how many trees, how strongly each contributes, when to stop.

parameter	type	default	effect
dart_drop_rate	float	0.0	DART: probability of dropping each existing tree per round. Above 0 enables DART regularization; incompatible with early stopping.
early_stopping_rounds	integer	0	Stop when the first validation objective stalls this many rounds, keeping the best iteration. 0 disables it; needs a valid set.
learning_rate	float	0.05	Shrinks each tree's contribution. Lower values need more rounds but generalize better, the classic accuracy-versus-iterations trade.
log_intervals	integer	0	Progress-logging frequency during fit. 0 is silent; higher prints more metric ticks. No effect on the trained model.
n_iters	integer	100	Number of boosting rounds. More rounds lower training loss but risk overfitting; pair with a smaller learning_rate.
random_seed	integer	42	Seeds the stochastic boosting choices, such as DART drops. Fixing it makes a run reproducible bit for bit.

tree

Per-tree shape and regularization, the primary overfitting controls.

parameter	type	default	effect
feature_fraction	float	1.0	Fraction of features sampled per tree. Below 1 decorrelates trees and speeds training, often improving generalization.
feature_seed	integer	2	Seeds the per-tree feature_fraction draws. Fixing it keeps feature subsampling reproducible across runs.
interaction_constraints	list	[]	Feature groups allowed to interact on one tree path. Restricts which features co-split, encoding domain structure and limiting interactions.
lambda_l1	float	0.0	L1 penalty on leaf weights. Above 0 pushes small leaf outputs to exactly zero, a sparser, more regularized fit.
lambda_l2	float	1.0	L2 penalty on leaf weights. Higher values shrink leaf outputs toward zero, smoothing predictions and reducing variance.
max_depth	integer	6	Maximum tree depth. Deeper trees capture more feature interactions but overfit and cost more; the primary complexity knob.
max_leaves	integer	31	Leaf cap for leafwise growth. 0 is unbounded (depth-capped). Fewer leaves regularize; more leaves fit finer structure.
min_child_hess	float	1.0	Minimum summed hessian per leaf. Higher values block splits on thin data, reducing overfitting; the hessian-weighted analog of min_child_weight.
min_data_in_leaf	integer	20	Minimum training rows per leaf. Higher values prevent tiny leaves fit to noise, a strong overfitting guard on small data.
min_gain_to_split	float	0.0	Minimum loss reduction to accept a split. Raising it prunes low-value splits and shrinks trees, curbing overfitting.
monotone_constraints	list	[]	Per-feature monotone direction: +1 increasing, -1 decreasing, 0 free. Forces predictions to respect known monotonic relationships. Node-splitting growers only.

sampler

Row subsampling, active only for the bernoulli and goss samplers.

parameter	type	default	effect
other_rate	float	0.1	goss sampler: fraction sampled from the remaining small-gradient rows. Higher samples more, nearer full-data accuracy but slower.
subsample	float	1.0	bernoulli sampler: fraction of rows drawn per tree. Below 1 adds randomness and speed, trading accuracy for less overfitting.
top_rate	float	0.2	goss sampler: fraction of large-gradient rows always kept. Higher retains more of the informative rows goss prioritizes.

bin_mapper

Histogram binning: how feature values become the bins that splits search over.

parameter	type	default	effect
max_bin	integer	255	Histogram bins per feature. More bins give finer split candidates at higher histogram cost; measured standings use 255 and were insensitive to small changes near it.
min_data_in_bin	integer	1	Minimum rows per histogram bin. Higher values merge sparse bins, coarsening splits and guarding against noise-driven cuts.
n_samples	integer	200000	Rows sampled to compute bin edges. More gives more accurate quantiles at higher binning cost; the default already stabilizes edges.
seed	integer	0	Seeds the row sample used for bin-edge quantiles. Fixing it keeps bin boundaries reproducible across runs.

objective

Extra parameters read only by the matching objective.

parameter	type	default	effect
huber_delta	float	1.0	huber objective: residual half-width of the L2 zone. Smaller behaves more like L1 (robust to outliers), larger like L2.
n_classes	integer	3	softmax objective: number of classes, labels 0 to K-1. Must match the data; sets the trees-per-round multiplier.
quantile_alpha	float	0.5	quantile objective: the target quantile in (0, 1). 0.5 is the median; higher tilts predictions toward that upper quantile.

metrics

Which metrics to report during fit and eval; no effect on the trained model.

parameter	type	default	effect
eval	list	[]	Metric names reported during eval. Empty uses the objective's defaults. Reporting only, no effect on the model.
fit	list	[]	Metric names reported during fit. Empty uses the objective's defaults. Reporting only, no effect on the model.

data

Dataset IO for the CLI; the Python API passes arrays instead of paths.

parameter	type	default	effect
format	string	"csv"	Input file format: csv or libsvm. Selects the parser and must match the files.
header	boolean	true	Whether CSV inputs have a header row. The wrong setting misreads the first row as data or as names.
ignore_columns	list	[]	Zero-based column indices to drop before training. Excludes ids or leaks without editing the file.
label_column	integer	0	Zero-based index of the label column in CSV inputs. Points the parser at the target.
libsvm_n_features	integer	0	libsvm only: force the feature count. 0 infers from the max index; set it when a split's max index is lower.
missing_nan	boolean	true	Treat NaN as missing, routed to each split's learned default branch. Off means NaN is an ordinary value.
missing_sentinel	float (optional)	unset	Extra numeric value treated as missing, alongside NaN. Unset by default; set it to flag a placeholder like -999.
test	string	""	Path to a test dataset scored after fit. CLI-only, like train.
train	string	""	Path to the training dataset. The CLI reads it; the Python API passes arrays instead.
valid	list	[]	Paths to validation datasets. The first drives early stopping; all are scored each logging tick.
weight_column	integer	-1	Zero-based index of a per-row weight column. -1 means unweighted; a valid index weights the loss per row.

parallel

Compute placement: CPU threads and CUDA device. No effect on the model bits.

parameter	type	default	effect
device_id	integer	0	CUDA device for cuda_ growers. Placement only: ignored by CPU growers and deliberately not stored in the model.
n_threads	integer	0	CPU threads for training. 0 auto-detects hardware threads, capped at 16. More threads speed fit; model bits are unchanged.