Install LightGBM 4.6.0: Deploy Microsoft’s Gradient Boosting

You want a gradient boosting model in production this afternoon. XGBoost feels heavy, sklearn’s GradientBoostingClassifier is single-threaded, and your dataset is 8 million rows. This is exactly where Microsoft gradient boosting – the framework the world knows as LightGBM – earns its keep. The catch: getting it installed cleanly isn’t always the one-liner the docs promise, especially on Apple Silicon or with a GPU.

This guide walks through deploying LightGBM 4.6.0 (the current stable release as of early 2026) with the actual commands that work, plus the failure modes nobody warns you about until you hit them.

What you’re actually installing

20x faster than conventional GBDT training. That’s the headline claim from the Ke et al. NeurIPS 2017 paper – and it still holds up. The two techniques behind it are Gradient-based One-Side Sampling (GOSS) and Exclusive Feature Bundling (EFB). You don’t need to understand either to install the thing, but knowing they exist explains why the library links against OpenMP so aggressively: parallelism is load-bearing, not optional.

One structural note before you clone anything: the project moved from microsoft/LightGBM to lightgbm-org/LightGBM on GitHub in March 2026 – same maintainers, new org. Old git clone URLs still redirect, but if you have CI scripts pinning that path, update them now rather than when a redirect eventually breaks.

System requirements

LightGBM is unusually forgiving on hardware. The pain is almost entirely in the build toolchain, not RAM or CPU.

The GPU story is where deployment plans quietly break. Per the official installation guide: the original GPU version (device_type=gpu) is OpenCL-based. The CUDA version (device_type=cuda) is a separate implementation – Linux only, NVIDIA GPU with compute capability 6.0 or higher, CUDA 11.0+ libraries. The CUDA path is not supported on Windows; use the OpenCL GPU version there. And GPU acceleration of any kind is not supported on macOS – so if you’re on a MacBook expecting GPU training, stop planning that now.

The recommended install path (pip)

Ninety percent of readers should stop reading and run this:

pip install lightgbm

That pulls lightgbm-4.6.0 (uploaded to PyPI on Feb 15, 2025) matching your platform – win_amd64, manylinux_2_28_x86_64, manylinux2014_aarch64, or macosx_12_0_arm64. On Linux there’s a bonus: manylinux_2_28 wheels ship with OpenCL GPU support baked in. Just pip install lightgbm and pass {"device": "gpu"} in params – no source build needed. That changed with the v4 release cycle and is still underappreciated.

For scikit-learn integration, add the extra:

pip install "lightgbm[scikit-learn]"

Pro tip: If you need MPI-based distributed training, don’t try to bolt it on later. Reinstall with pip install lightgbm --config-settings=cmake.define.USE_MPI=ON. On Windows, compilation with MinGW-w64 is not supported – use VS Build Tools instead.

The macOS trap that eats an afternoon

Here’s where the tutorial internet fails most people. On Apple Clang builds, install OpenMP first, then the package:

brew install libomp
pip install lightgbm

Looks fine. It compiles. Then you try to fit models in parallel with ThreadPoolExecutor and get OMP: Error #13: Assertion failure at kmp_runtime.cpp(3689) or OMP: Error #131: Thread identifier invalid. Setting nthreads=1 doesn’t help.

The root cause, per GitHub issue #4229: this works with libomp version 11, not 12+. The community fix is a version downgrade:

brew unlink libomp
wget https://raw.githubusercontent.com/Homebrew/homebrew-core/fb8323f2b170bd4ae97e1bac9bf3e2983af3fdb0/Formula/libomp.rb
brew install libomp.rb

Yes, it’s ugly. Yes, it’s still the working answer as of early 2026 for users hitting this specific parallel-fit failure mode.

Apple Silicon: pip will lie to you

M1/M2/M3 Macs have a specific failure mode worth knowing upfront. pip install lightgbm sometimes appears to succeed and then throws at import time. Or it fails at build with CMake Error: Could NOT find OpenMP_C (missing: OpenMP_C_FLAGS OpenMP_C_LIB_NAMES) – because Homebrew on Apple Silicon lives at /opt/homebrew, not /usr/local, and CMake’s default search paths miss it entirely (per GitHub issue #5549).

Skip the fight. Use conda-forge:

conda create -n lgbm python=3.11
conda activate lgbm
conda install -c conda-forge lightgbm

Community reports converge on this – pip on M1 is a coin flip, conda-forge is reliable. As a workaround you can also pass -DOpenMP_ROOT=$(brew --prefix libomp) to the CMake invocation if you prefer a source build, but that path has more moving parts.

Building from source (when you need GPU or MPI)

If the prebuilt wheel doesn’t fit your case – custom CUDA path, RHEL 7 with old glibc, or a stripped static library – compile it. Per the official installation guide:

git clone --recursive https://github.com/lightgbm-org/LightGBM
cd LightGBM
cmake -B build -S .
cmake --build build -j4

For the CUDA build on Linux with an NVIDIA GPU, add the -DUSE_CUDA=ON flag – refer to the official installation guide for current compiler version requirements, since these change with CUDA toolkit releases. Then install the Python package pointing at the compiled library: sh ./build-python.sh install --precompile.

A word on when source builds are actually worth it: for most setups they aren’t. The manylinux_2_28 pip wheel handles OpenCL GPU and covers the vast majority of Linux targets. Source builds pay off mainly when you’re on an unusual glibc version, need a custom CUDA toolkit path, or want to link a static library into a container with no system-level OpenMP dependency. If none of those apply – stay with pip or conda-forge and save yourself the CMake debugging session.

Verify it actually works

A version check alone is misleading – the import can succeed and OpenMP can still be broken. Run a real training step:

python -c "
import lightgbm as lgb
import numpy as np
print('version:', lgb.__version__)

X = np.random.rand(1000, 10)
y = (X.sum(axis=1) > 5).astype(int)
model = lgb.LGBMClassifier(n_estimators=50, n_jobs=-1).fit(X, y)
print('trained OK, feature importances:', model.feature_importances_[:3])
"

Expected output: version: 4.6.0 followed by a small array. If you get OSError: libgomp.so.1: cannot open shared object file, the OpenMP runtime isn’t installed – on Ubuntu it’s apt install libgomp1, on RHEL it’s yum install libgomp.

Common errors, real fixes

• OSError: libgomp.so.1: cannot open shared object file – install the OpenMP runtime package (libgomp1 on Debian/Ubuntu, libgomp on RHEL family).
• OMP: Error #13 / #131 on macOS under parallel fit – downgrade Homebrew libomp to version 11 (see the snippet above).
• CMake Error: Could NOT find OpenMP_C on Apple M1 – switch to conda-forge, or pass -DOpenMP_ROOT=$(brew --prefix libomp) to the CMake invocation.
• Wheel installs but device='gpu' throws “GPU Tree Learner was not enabled” – you’re on a non-manylinux_2_28 wheel (e.g., older Linux distro or Windows). Rebuild from source with USE_GPU=ON plus Boost and OpenCL headers.
• Windows: MSBuild fails with Platform Toolset error – confirm VS Build Tools are installed and that your CMake generator targets the correct toolset version.

Upgrading and uninstalling

One thing to know before upgrading: LightGBM uses Intended Effort Versioning (EffVer) – new minor versions can contain breaking changes, but these are typically small or limited to less-frequently-used parts of the project (per the Read the Docs changelog). So pip install --upgrade lightgbm is usually safe, but skim the release notes first if you’re upgrading across minor versions in a production pipeline.

pip install --upgrade lightgbm

To remove:

pip uninstall lightgbm
# then, only if you installed it manually:
brew uninstall libomp # macOS
# or
sudo apt remove libgomp1 # Debian/Ubuntu

Don’t remove OpenMP runtime libraries reflexively – other scientific Python packages (numpy with MKL, scikit-learn, PyTorch) may depend on them.

Next action

Run the verification snippet above right now. If it prints 4.6.0 and a feature-importance array, you’re done – move on to actually tuning the model. If it errors, jump to the matching entry in the errors list, apply the fix, and re-run. Bookmark the official docs for parameter reference; you’ll be back for num_leaves and min_data_in_leaf tuning within the week.

FAQ

Do I need XGBoost uninstalled before installing LightGBM?

No. They coexist without conflict in the same environment.

Why does conda-forge give me an older LightGBM than pip?

Conda-forge builds lag PyPI by a few weeks because feedstock maintainers need to update recipes and CI has to complete across all platforms. If you’re on Apple Silicon and hit pip install failures, an older conda-forge version is still a fine trade for a working environment – the API differences between minor 4.x releases are small under EffVer. Once conda-forge catches up, run conda update -c conda-forge lightgbm.

Can I use LightGBM on a Raspberry Pi or ARM server?

Yes – there’s a manylinux2014_aarch64 wheel on PyPI as of 4.6.0, so pip install lightgbm works on 64-bit ARM Linux without a source build. Performance won’t match an x86 workstation with AVX2, but for inference or small-dataset training on ARM64 servers (Graviton, Ampere) it’s fully supported.