[python-package] use PEP 639 license metadata, bump to`scikit-build-core>=0.11.0`, use `hatchling` instead of `setuptools` #7135

jameslamb · 2026-01-20T00:23:45Z

Fixes #6665
Replaces #6681

This project uses setuptools when building a Python wheel with a pre-compiled lib_lightgbm.{dll,dylib,so}, like this:

cmake -B build -S .
cmake --build build --target _lightgbm
sh build-python.sh install --precompile

That's helpful for users building with customizations (like the MPI version), and that pattern used in all the TASK=regular CI jobs here.

For a few months, that's been raising warnings about license metadata, warning that a new setuptools in February 2026 may turn those warnings into errors.

warning text (click me)

Warnings below from a recent regular job (build link)

/tmp/build-env-vhotg1gp/lib/python3.13/site-packages/setuptools/config/_apply_pyprojecttoml.py:82: SetuptoolsDeprecationWarning: `project.license` as a TOML table is deprecated
!!

        ********************************************************************************
        Please use a simple string containing a SPDX expression for `project.license`. You can also use `project.license-files`. (Both options available on setuptools>=77.0.0).

        By 2026-Feb-18, you need to update your project and remove deprecated calls
        or your builds will no longer be supported.

        See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for details.
        ********************************************************************************

!!
  corresp(dist, value, root_dir)
/tmp/build-env-vhotg1gp/lib/python3.13/site-packages/setuptools/config/_apply_pyprojecttoml.py:61: SetuptoolsDeprecationWarning: License classifiers are deprecated.
!!

        ********************************************************************************
        Please consider removing the following classifiers in favor of a SPDX license expression:

        License :: OSI Approved :: MIT License

        See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for details.
        ********************************************************************************

!!
  dist._finalize_license_expression()
/tmp/build-env-vhotg1gp/lib/python3.13/site-packages/setuptools/dist.py:759: SetuptoolsDeprecationWarning: License classifiers are deprecated.
!!

        ********************************************************************************
        Please consider removing the following classifiers in favor of a SPDX license expression:

        License :: OSI Approved :: MIT License

        See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for details.
        ********************************************************************************

!!
  self._finalize_license_expression()

This resolves those warnings with following changes:

updating the way license metadata is spelled
moving the floor on scikit-build-core to the earliest version that supported PEP 639 (v0.11.0)
switching from setuptools to hatchling

I found those specific floors while doing something similar for RAPIDS projects: rapidsai/build-planning#152

Benefits of these changes

prevents builds from being broken with newer setuptools this year
- including on conda-forge, which has similar warnings because the lightgbm feedstock patches in setuptools as the build backed (conda-forge/lightgbm-feedstock code link)
permanently fixes [python-package] UNKNOWN python package #6665 and reduces the risk of it happening in the future (details below)
pulls in fixes, performance improvements, etc. in newer scikit-build-core
makes it easier for security and compliance scanners to extract license data from lightgbm installations

Notes for Reviewers

Why `scikit-build-core>=0.11.0`?

Tat's the first version that support PEP 639 license metadata.

I recently updated all of RAPIDS to that version (rapidsai/build-planning#152) and didn't encounter any problems, so I think it's safe.

why switch to `hatchling`? how does that affect portability?

hatchling makes --precompile builds of lightgbm more portable and more backwards-compatible than the current setup with setuptools 😁

hatchling is a pure Python package (just a py3-none-any wheel), so it doesn't bring any new constraints on GLIBC version, CPU architecture, or operating system.

It also avoids these setuptools-specific problems:

setuptools being system-installed on some linux distributions as a hard requirement of pip (see [python-package] UNKNOWN python package #6665, especially [python-package] UNKNOWN python package #6665 (comment))
setuptools sometimes being declared as a runtime dependency of lightgbm's depenendencies
- example: older pandas packages on conda-forge have a runtime dependency on setuptools<60
- build with some environment conflicts caused by that: (link)

For these --precompile builds, we only need very very simple Python packaging: create a zip archive out of a directory and write the appropriate wheel metadata. No compiler flags, handling of symlinks, other configuration for sdists, etc.

This is a long-term fix for #6665, replacing #6681 😁 (see #6665 (comment))

why `hatchling>=1.27.0` specifically?

hatchling==1.27.0 was the final version to support Python 3.9 (pypa/hatch#2097), the oldest Python lightgbm supports.

jameslamb · 2026-01-20T04:59:55Z

build-python.sh

-        BUILD_SDIST=true
-        BUILD_WHEEL=false
+        BUILD_SDIST=false
+        BUILD_WHEEL=true


With hatchling we have tighter control over package contents, so --precompile can build a wheel 😁

jameslamb · 2026-01-20T05:00:37Z

build-python.sh

+    cd ..
    if test "${BUILD_WHEEL}" = true; then
-        PACKAGE_NAME="$(echo lightgbm*.whl)"
+        PACKAGE_FILE="$(echo dist/lightgbm*.whl)"


If this echo is portable enough, then we can avoid using --find-links in pip.

Not strictly related to the rest of this change, but just something else I noticed that could help with building from source using build-python.sh.

jameslamb · 2026-01-20T05:02:16Z

docs/GPU-Tutorial.rst


    sudo apt-get -y install python-pip
-    sudo -H pip install setuptools numpy scipy scikit-learn -U
+    sudo -H pip install numpy scipy scikit-learn -U


setuptools was only helpful here because it gets system installed by apt-get install python-pip on Ubuntu, and so needed to be upgraded.

Any other build-time requirements (like scikit-build-core) don't need to be separately installed by default, because they'll be set up in pip's isolated build environment.

jameslamb · 2026-01-20T05:08:36Z

build-python.sh

+
+    # at this point, if 'install' was passed but the package type wasn't indicated, prefer wheel
+    if test "${BUILD_SDIST}" = false && test "${BUILD_WHEEL}" = false; then
+        echo "[INFO] 'install' passed but no package type ('bdist_wheel', 'sdist') chosen. Defaulting to 'bdist_wheel'."


Test like this:

$ sh build-python.sh install ... [INFO] 'install' passed but no package type ('bdist_wheel', 'sdist') chosen. Defaulting to 'bdist_wheel'. [INFO] --- building wheel --- * Creating isolated environment: venv+pip... * Installing packages in isolated environment: - scikit-build-core>=0.11.0 * Getting build dependencies for wheel... * Building wheel... ... Successfully built lightgbm-4.6.0.99-py3-none-macosx_14_0_arm64.whl [INFO] --- installing lightgbm --- Processing ./dist/lightgbm-4.6.0.99-py3-none-macosx_14_0_arm64.whl Installing collected packages: lightgbm Attempting uninstall: lightgbm Found existing installation: lightgbm 4.6.0.99 Uninstalling lightgbm-4.6.0.99: Successfully uninstalled lightgbm-4.6.0.99 Successfully installed lightgbm-4.6.0.99

jameslamb · 2026-01-20T05:27:07Z

docs/GPU-Tutorial.rst


-    sudo apt-get -y install python-pip
-    sudo -H pip install setuptools numpy scipy scikit-learn -U
+    sudo apt-get -y install python3-pip python3-venv


python3-venv is required because now these commands build a wheel (not an sdist), with build isolation.

Found that in testing on Ubuntu 22.04: #6665 (comment)

jameslamb · 2026-01-20T05:28:21Z

build-python.sh

-        echo "" >> ./MANIFEST.in
+
+# replace build backend configuration
+cat >> ./pyproject.toml <<EOF


Using heredocs for readability. See this old review thread: #6681 (comment)

borchero

Nice! Big fan of hatchling ;)

jameslamb · 2026-01-21T14:59:02Z

Thanks @borchero . Yeah I've started trying it out recently and am really liking it!

Inspired by pyOpenSci's write-up here: https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-build-tools.html#about-hatch

(cc @ucodery @lwasser thanks 😊)

[python-package] use PEP 639 license metadata

05727ca

jameslamb added the maintenance label Jan 20, 2026

conda-forge skipped setuptools 77.7

0b4e71e

jameslamb changed the title ~~WIP: [python-package] use PEP 639 license metadata, 'scikit-build-core>=0.11.0', 'setuptools>=77.0.0'~~ WIP: [python-package] use PEP 639 license metadata, bump toscikit-build-core>=0.11.0, use hatchling instead of setuptools Jan 20, 2026

jameslamb added 5 commits January 19, 2026 21:45

use hatchling instead

4b50ca4

misc fixes

7a53299

comment out some CI, remove --find-links

929b830

fix paths

cdcddae

change install rules... with hatchling, we are building a wheel

ddf3b0e

microsoft deleted a comment Jan 20, 2026

jameslamb commented Jan 20, 2026

View reviewed changes

use heredoc instead of echo

96d5b94

jameslamb mentioned this pull request Jan 20, 2026

[python-package] UNKNOWN python package #6665

Closed

add python3-venv as required package in GPU tutorial

d62ca8a

jameslamb commented Jan 20, 2026

View reviewed changes

jameslamb mentioned this pull request Jan 20, 2026

WIP: [ci] [python-package] support setuptools<61 in build-python.sh (fixes #6665) #6681

Closed

jameslamb commented Jan 20, 2026

View reviewed changes

Merge branch 'master' into spdx-license-data

20fa61a

jameslamb changed the title ~~WIP: [python-package] use PEP 639 license metadata, bump toscikit-build-core>=0.11.0, use hatchling instead of setuptools~~ [python-package] use PEP 639 license metadata, bump toscikit-build-core>=0.11.0, use hatchling instead of setuptools Jan 20, 2026

jameslamb marked this pull request as ready for review January 20, 2026 13:05

jameslamb requested review from StrikerRUS, borchero, guolinke, jmoralez and shiyu1994 as code owners January 20, 2026 13:05

jameslamb added the awaiting review label Jan 20, 2026

borchero approved these changes Jan 20, 2026

View reviewed changes

jameslamb removed the awaiting review label Jan 21, 2026

jameslamb merged commit 6af94aa into master Jan 21, 2026
76 checks passed

jameslamb deleted the spdx-license-data branch January 21, 2026 14:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[python-package] use PEP 639 license metadata, bump to`scikit-build-core>=0.11.0`, use `hatchling` instead of `setuptools` #7135

[python-package] use PEP 639 license metadata, bump to`scikit-build-core>=0.11.0`, use `hatchling` instead of `setuptools` #7135

jameslamb commented Jan 20, 2026 •

edited

Loading

Uh oh!

jameslamb Jan 20, 2026

Uh oh!

jameslamb Jan 20, 2026

Uh oh!

jameslamb Jan 20, 2026

Uh oh!

jameslamb Jan 20, 2026

Uh oh!

jameslamb Jan 20, 2026

Uh oh!

jameslamb Jan 20, 2026

Uh oh!

borchero left a comment

Uh oh!

jameslamb commented Jan 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

[python-package] use PEP 639 license metadata, bump toscikit-build-core>=0.11.0, use hatchling instead of setuptools #7135

[python-package] use PEP 639 license metadata, bump toscikit-build-core>=0.11.0, use hatchling instead of setuptools #7135

Conversation

jameslamb commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benefits of these changes

Notes for Reviewers

Why scikit-build-core>=0.11.0?

why switch to hatchling? how does that affect portability?

why hatchling>=1.27.0 specifically?

Uh oh!

jameslamb Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

jameslamb Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

jameslamb Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

jameslamb Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

jameslamb Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

jameslamb Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

borchero left a comment

Choose a reason for hiding this comment

Uh oh!

jameslamb commented Jan 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

[python-package] use PEP 639 license metadata, bump to`scikit-build-core>=0.11.0`, use `hatchling` instead of `setuptools` #7135

[python-package] use PEP 639 license metadata, bump to`scikit-build-core>=0.11.0`, use `hatchling` instead of `setuptools` #7135

jameslamb commented Jan 20, 2026 •

edited

Loading

Why `scikit-build-core>=0.11.0`?

why switch to `hatchling`? how does that affect portability?

why `hatchling>=1.27.0` specifically?