Install & Compatibility
Where this runs
tested against v4.7.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 13.9s · import 0.000s · 543MB
554MB installed
● package 554MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
lightgbm
✓ import lightgbm as lgb
LGBMClassifier
✓ from lightgbm import LGBMClassifier
LGBMRegressor
✓ from lightgbm import LGBMRegressor
Dataset
✓ lgb_train = lgb.Dataset(X_train, y_train)
✗ lgb.Dataset(X_train, y_train, feature_name=feature_names, categorical_feature=categorical_features)
As of v4.0.0, 'feature_name' and 'categorical_feature' parameters should be set directly on the `Dataset` object or inferred, not passed to the constructor or `train`/`cv` functions.
This quickstart demonstrates how to train a binary classification model using LightGBM's scikit-learn compatible API (`LGBMClassifier`). It covers data preparation, model initialization, training with early stopping, prediction, and evaluation. For non-scikit-learn API, `lgb.Dataset` and `lgb.train` are used.
import numpy as np
import lightgbm as lgb
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score
# Generate some dummy data
X = np.random.rand(1000, 10)
y = np.random.randint(0, 2, 1000)
# Split data into training and testing sets
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
# Initialize and train the LGBMClassifier
# Using scikit-learn API for convenience
model = lgb.LGBMClassifier(objective='binary', random_state=42)
model.fit(X_train, y_train,
eval_set=[(X_test, y_test)],
callbacks=[lgb.early_stopping(10)]) # Early stopping after 10 rounds without improvement
# Make predictions
y_pred = model.predict(X_test)
# Evaluate the model
accuracy = accuracy_score(y_test, y_pred)
print(f"Model Accuracy: {accuracy:.4f}")
lightgbm --version
Debug
Known issues
breakingLightGBM v4.x introduced significant breaking changes. Key updates include making `Booster` and `Dataset` `handle` attributes private, removal of a hard `scikit-learn` dependency (now optional), and switching to PEP 517/518 builds (removal of `setup.py`). Furthermore, `feature_name` and `categorical_feature` parameters should now be set on the `lgb.Dataset` object directly, not passed to `train()` or `cv()` functions. CUDA 10 support was dropped in favor of CUDA 12.fixReview release notes for v4.0.0. Update code to use `lgb.Dataset.set_feature_name()` and `lgb.Dataset.set_categorical_feature()` or ensure features are correctly typed/named. Ensure `scikit-learn>=0.24.2` is installed for `LGBMClassifier/Regressor`.
affects: 4.0.0 and above
gotchaLightGBM can handle categorical features natively, but they should be converted to integer types (e.g., 0, 1, 2...). Passing non-integer or excessively large integer values as categorical features can lead to warnings or unexpected behavior.fixEnsure all categorical features are explicitly converted to `int` type (e.g., using `LabelEncoder` or pandas `astype('category').cat.codes`) before creating `lgb.Dataset` or fitting `LGBMClassifier/Regressor`. Values should ideally range from 0 to `num_categories - 1`. affects: All versions
gotchaLightGBM is prone to overfitting, especially on small datasets (<10,000 records) or with excessively deep trees.fixImplement hyperparameter tuning for `num_leaves`, `max_depth`, `min_data_in_leaf`, and regularization parameters (`lambda_l1`, `lambda_l2`). Always use early stopping with a validation set during training. Consider `min_sum_hessian_in_leaf` and data/feature bagging (`bagging_fraction`, `feature_fraction`).
affects: All versions
gotchaUsing GPU acceleration requires specific setup beyond `pip install lightgbm`. While newer versions (v4.x) have improved CUDA support, you typically need OpenCL Runtime libraries. Some advanced GPU features or specific CUDA versions might require building from source.fixFor basic GPU usage, ensure OpenCL Runtime libraries are installed (often via GPU drivers). For specific CUDA versions or advanced GPU features, consult the official LightGBM installation guide for building from source or specialized wheels. Use `device='gpu'` in parameters.
affects: All versions, especially 3.x and earlier for CUDA compatibility
gotchaOn Linux, if LightGBM hangs when multithreading (OpenMP) and using forking (e.g., in multiprocessing scenarios), it's a known bug.fixSet `nthreads=1` in your LightGBM parameters to disable LightGBM's internal multithreading when using forking mechanisms.
affects: All versions (Linux)
breakingLightGBM's native library is compiled with OpenMP support and requires `libgomp.so.1` (GNU OpenMP runtime library) to be present on the system. This library is a common dependency for many scientific computing packages but is often not pre-installed in minimal Linux environments (e.g., lightweight Docker images), leading to an `OSError` upon import.fixInstall `libgomp1` (Debian/Ubuntu-based: `apt-get update && apt-get install -y libgomp1`), `libgomp` (RedHat/Fedora-based: `yum install libgomp` or `dnf install libgomp`), or the equivalent OpenMP runtime library package for your Linux distribution. This ensures the shared library is available at runtime.
affects: All versions
gotchaBuilding LightGBM from source (e.g., when a pre-built wheel is not available for your specific Python version or architecture, common on minimal Linux distributions like Alpine) requires a C/C++ compiler and other development tools.fixEnsure your environment has necessary build tools, including a C/C++ compiler (e.g., `gcc` and `g++` on Linux), CMake, and Ninja. For Alpine Linux, this often means installing `build-base`, `cmake`, and `ninja` packages (e.g., `apk add build-base cmake ninja`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'lightgbm'
The 'lightgbm' package is not installed in the current Python environment or the environment where the code is being executed (e.g., Jupyter kernel).
fixInstall the 'lightgbm' package using pip or conda: `pip install lightgbm` or `conda install -c conda-forge lightgbm`
FileNotFoundError: Could not find module 'C:\...\lightgbm\lib_lightgbm.dll' (or one of its dependencies)
LightGBM relies on a native shared library (e.g., `lib_lightgbm.dll` on Windows, `.so` on Linux, `.dylib` on macOS) and its dependencies (like OpenMP runtime) which cannot be found or loaded by the Python environment. This is common with Python 3.8+ on Windows or missing OpenMP on Linux/macOS.
fixFor Windows Python 3.8+, try `os.add_dll_directory("path_to_lightgbm_dll")` before importing lightgbm, or ensure Visual C++ Redistributable is installed. For Linux/macOS, ensure OpenMP is installed (e.g., `brew install libomp` on macOS, `sudo apt-get install libgomp1` on Debian/Ubuntu). Using `conda install -c conda-forge lightgbm` often resolves these dependency issues by providing pre-built packages with necessary runtimes. AttributeError: module 'lightgbm' has no attribute 'LGBMClassifier'
This most commonly occurs when a local Python script or directory is named `lightgbm.py` or `lightgbm/`, shadowing the installed `lightgbm` package. It can also happen if the package is corrupted or an old version is installed.
fixRename any local files or directories named `lightgbm.py` or `lightgbm/` in your project path. If that doesn't resolve the issue, try reinstalling the package: `pip uninstall lightgbm && pip install lightgbm`.
AttributeError: 'Booster' object has no attribute 'attr'
The `attr` method was removed from the `Booster` object in LightGBM version 4.0.0. This often indicates a version incompatibility, particularly when using tools that rely on older LightGBM APIs.
fixIf your application requires the `attr` method (e.g., for compatibility with `onnxmltools`), downgrade LightGBM to a version prior to 4.0.0, for example: `pip install --force-reinstall "lightgbm==3.3.5"`.
OSError: [WinError 126] The specified module could not be found
On Windows, LightGBM requires the Visual C++ Redistributable for Visual Studio 2015-2022 to be installed for its C++ binaries to function correctly.
fixDownload and install the latest Visual C++ Redistributable for Visual Studio from Microsoft's official website.
Upgrade
Version history
4.7.0latest on PyPI · released Jul 18, 2026
Audit
Dependencies
numpyrequiredCommonly used for data handling and is often a prerequisite for data science workflows.
pandasoptionalIntegration with pandas DataFrames is a common use case; installable via 'lightgbm[pandas]'.
scikit-learnoptionalProvides a scikit-learn compatible API (LGBMClassifier, LGBMRegressor); installable via 'lightgbm[scikit-learn]'.
daskoptionalFor distributed training capabilities; installable via 'lightgbm[dask]'.
OpenCL Runtime librariesoptionalRequired for GPU support on Windows and Linux; often included with NVIDIA/AMD drivers.
libompoptionalRequired on macOS for OpenMP support and multithreading functionality.
C++ Compiler (GCC/Clang on Linux/macOS, MSVC on Windows)optionalNecessary for building LightGBM from source or for some advanced configurations, though wheels usually include a pre-compiled library.