Build Python package from source
Warning
This page describes the new approach for building using standard Python tools that works since this commit.
For building with earlier versions see these pages:
Source code
CatBoost source code is stored as a Git repository on GitHub at https://github.com/catboost/catboost/. You can obtain a local copy of this Git repository by running the following command from a command line interpreter (you need to have Git command line tools installed):
git clone https://github.com/catboost/catboost.git
Later in this document $CATBOOST_SRC_ROOT
refers to the root dir of the local working copy of the source code cloned from the GitHub CatBoost repository.
Dependencies and requirements
-
As CatBoost Python package has a native extension library as its' core build environment setup for CMake is required.
-
Other setup dependencies that can be formulated as python packages are listed in
pyproject.toml
'sbuild-system.requires
and insetup.py
in standardsetup_requires
parameter and processed using standard Python tools. -
Installation dependencies are listed in
setup.py
in standardinstall_requires
parameter and processed using standard Python tools.
Training on GPU requires NVIDIA Driver of version 418.xx or higher.
Building
Open the $CATBOOST_SRC_ROOT/catboost/python-package
directory from the local copy of the CatBoost repository.
Use Python's standard procedures:
Build the wheel distribution
Warning
Note that built Python wheels will be binary compatible only with the same Python X.Y versions.
python setup.py bdist_wheel <options>
Options can be listed by calling python setup.py bdist_wheel --help
.
One important option is --prebuilt-extensions-build-root-dir=<path>
. It allows to use already built binary _catboost
extension shared library. See Build native artifacts. Set this option value to $CMAKE_BINARY_DIR
.
The resulting wheel distribution will be created in dist/catboost-<version>-<...>.whl
Build the source distribution (sdist)
python -m build --sdist
The resulting source distribution will be created in dist/catboost-<version>.tar.gz
file.
Other useful commands
-
build_widget
. Build CatBoost widget.python setup.py build_widget
Useful if widget code remains unchanged but you want to rebuild other parts. Then run
build_widget
once and then in subsequent calls tobdist_wheel
or other commands use--prebuilt-widget
option.
Installation
Directly from the source directory
Builds in the process. So build environment setup for CMake is required.
python -m pip install . <options>
You can pass options to setup.py's install
stage by using --install-option
options like this:
python -m pip install . --install-option=--with-hnsw --install-option=--with-cuda=/usr/local/cuda-11
editable install
CreateBuilds in the process. So build environment setup for CMake is required.
python -m pip install --editable . <options>
You can pass options to setup.py's install
stage by using --install-option
options like this:
python -m pip install --install-option=--with-hnsw --install-option=--with-cuda=/usr/local/cuda-11/ --editable .
Install from the built wheel
python -m pip install <path-to-wheel>
Install from the source distribution
Builds in the process. So build environment setup for CMake is required.
python -m pip install <path-to-sdist-tar.gz>