---
metadata:
- name: generator
content: Diplodoc Platform v5.50.3
alternate:
- https://catboost.ai/docs/en/installation/python-installation-method-build-from-source.md
---
> **Documentation Index:** Fetch the complete configuration index at https://catboost.ai/docs/en/llms.txt
# Build Python package from source
{% note info %}
CatBoost Python package supports only [CPython Python implementation](https://en.wikipedia.org/wiki/CPython).
{% endnote %}
{% note warning %}
This page describes the new approach for building using standard Python tools that works since [this commit](https://github.com/catboost/catboost/commit/f37d091421089231ed3c74a0431fff1c3544d606).
For building with earlier versions see these pages:
- [In-place build on Linux and macOS](https://catboost.ai/docs/en/installation/python-installation-method-build-from-source-linux-macos-using-ya-make.md)
- [In-place build on Windows](https://catboost.ai/docs/en/installation/python-installation-method-build-from-source-windows-using-ya-make.md)
- [Build a wheel using mk_wheel.py](https://catboost.ai/docs/en/installation/python-installation-method-build-a-wheel-package.md#mk-wheel)
{% endnote %}
## Source code
CatBoost source code is stored as a [Git](https://git-scm.com/) repository on GitHub at . 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
1. As CatBoost Python package has a native extension library as its' core [build environment setup for CMake](https://catboost.ai/docs/en/installation/build-environment-setup-for-cmake.md) is required.
1. `build` Python package.
1. `setuptools` Python package, version 64.0+. Installed by default for Python < 3.12, an explicit installation is needed for Python 3.12+.
{% cut "Previous requirements" %}
For revisions before [5c26d15](https://github.com/catboost/catboost/commit/5c26d15fa5f218966a3dafb3f047d7f35650f235) supported 'setuptools' versions were >= 64.0 and < 81.0.
{% endcut %}
1. Other setup dependencies that can be formulated as python packages are listed in [`pyproject.toml`](https://github.com/catboost/catboost/blob/master/catboost/python-package/pyproject.toml)'s `build-system.requires` and in [`setup.py`](https://github.com/catboost/catboost/blob/master/catboost/python-package/setup.py) in standard `setup_requires` parameter and processed using standard Python tools.
{% note info %}
For some reason Python 3.12 fails to automatically resolve build/setup dependencies in a way that they are buildable so it is recommended to install the following packages using pip explicitly:
- setuptools
- wheel (if using setuptools < 70.1.0, ['wheel' functionality has been integrated into setuptools since 70.1.0](https://github.com/pypa/setuptools/issues/1386) )
- jupyterlab (3.x, 4.x is not supported yet, see [the relevant issue](https://github.com/catboost/catboost/issues/2533))
- conan (2.4.1+, for revisions before [21a3f85](https://github.com/catboost/catboost/commit/21a3f856c118b8c2514f0307ca7b013d6329015e) only conan 1.x with versions 1.62.0+ is supported)
{% endnote %}
1. For building CatBoost visualization widget bundled together with the python package (enabled by default) additional setup is required:
1. [Node.js](https://nodejs.org/) installation with `npm` command accessible from the shell.
1. [`rimraf` Node.js package](https://www.npmjs.com/package/rimraf) installed with `npm`'s `--global` option (this way `rimraf` command will be accessible from the shell).
1. [`yarn` package manager](https://yarnpkg.com/), version from 1.x series, `1.22.10` or later. Installed with `npm`'s `--global` option (this way `yarn` command will be accessible from the shell)
An example command to install: `npm install --global yarn@1.22.10`.
If you don't need CatBoost visualization widget support you can disable it's building and bundling with the CatBoost python package by passing `--no-widget` build/installation option.
1. Installation dependencies are listed in [`setup.py`](https://github.com/catboost/catboost/blob/master/catboost/python-package/setup.py) in standard `install_requires` parameter and processed using standard Python tools.
1. User-defined functions
If you want to use [custom metrics or objectives implemented in your own python code](https://catboost.ai/docs/en/features/custom-loss-functions.md) you should install [`numba`](https://numba.pydata.org/) package to speed up the code execution using JIT compilation.
If you want to use custom metrics or objectives on GPUs with CUDA support you must install [`numba`](https://numba.pydata.org/) package for JIT compilation of CUDA code.
Installation of [`numba-cuda`](https://github.com/NVIDIA/numba-cuda) package is also encouraged.
CUDA itself (not only drivers) must be installed on machines where this code is executed.
See [`numba` CUDA support documentation](https://numba.readthedocs.io/en/stable/cuda/overview.html) for more details.
These packages are not listed in package requirements that are installed automatically because they are not needed for other functionality.
Training or inference on CUDA-enabled GPUs requires NVIDIA Driver of version 450.80.02 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 {#build-wheel}
{% note info %}
CUDA architectures to generate device code for are specified using [`CMAKE_CUDA_ARCHITECTURES` variable](https://cmake.org/cmake/help/v3.24/variable/CMAKE_CUDA_ARCHITECTURES.html), although the default value is non-standard, [specified in `cuda.cmake`](https://github.com/catboost/catboost/blob/5fb7b9def07f4ea2df6dcc31b5cd1e81a8b00217/cmake/cuda.cmake#L7). The default value is intended to provide broad GPU compatibility and supported only when building with CUDA 11.8.
The most convenient way to override the default value is to use [`CUDAARCHS` environment variable](https://cmake.org/cmake/help/v3.24/envvar/CUDAARCHS.html).
{% endnote %}
{% note warning %}
Note that built Python wheels will be compatible only with:
- the same platform that you build them on (i.e. `linux-x86_64`, `macos-arm64` etc.). Cross-compilation on Linux and building universal2 - compatible packages on macOS are possible but complicated, you can look at [ci/build_all.py script](https://github.com/catboost/catboost/blob/master/ci/build_all.py) for details.
- the same Python X.Y versions as the Python interpreter that you run the build command with.
{% endnote %}
```
python -m build --wheel --config-setting=--global-option=bdist_wheel
```
`bdist_wheel` options should be specified in the following way: `--config-setting=--global-option=--` or `--config-setting=--global-option=--=`
Example:
```
python -m build --wheel --config-setting=--global-option=bdist_wheel --config-setting=--global-option=--with-hnsw --config-setting=--global-option=--prebuilt-extensions-build-root-dir=/home/user/catboost/build/
```
You can also use older non-[PEP517](https://peps.python.org/pep-0517/) compliant way to build wheels:
```
python setup.py bdist_wheel
```
But it is deprecated and this command does not work properly for CatBoost on recent macOS versions (14+).
Options can be listed by calling `python setup.py bdist_wheel --help`.
One important option is `--prebuilt-extensions-build-root-dir=`. It allows to use already built binary `_catboost` extension shared library. See [Build native artifacts](https://catboost.ai/docs/en/installation/build-native-artifacts.md). Set this option value to `$CMAKE_BINARY_DIR`.
The resulting wheel distribution will be created in `dist/catboost--<...>.whl`
### Build the source distribution (sdist)
```
python -m build --sdist
```
The resulting source distribution will be created in `dist/catboost-.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 to `bdist_wheel` or other commands use `--prebuilt-widget` option.
## Installation
### [Directly from the source directory](https://pip.pypa.io/en/stable/topics/local-project-installs/#regular-installs)
Builds in the process. So [build environment setup for CMake](https://catboost.ai/docs/en/installation/build-environment-setup-for-cmake.md) is required.
{% note info %}
CUDA architectures to generate device code for are specified using [`CMAKE_CUDA_ARCHITECTURES` variable](https://cmake.org/cmake/help/v3.24/variable/CMAKE_CUDA_ARCHITECTURES.html), although the default value is non-standard, [specified in `cuda.cmake`](https://github.com/catboost/catboost/blob/5fb7b9def07f4ea2df6dcc31b5cd1e81a8b00217/cmake/cuda.cmake#L7). The default value is intended to provide broad GPU compatibility and supported only when building with CUDA 11.8.
The most convenient way to override the default value is to use [`CUDAARCHS` environment variable](https://cmake.org/cmake/help/v3.24/envvar/CUDAARCHS.html).
{% endnote %}
```
python -m pip install .
```
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
```
### Create [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)
Builds in the process. So [build environment setup for CMake](https://catboost.ai/docs/en/installation/build-environment-setup-for-cmake.md) is required.
{% note info %}
CUDA architectures to generate device code for are specified using [`CMAKE_CUDA_ARCHITECTURES` variable](https://cmake.org/cmake/help/v3.24/variable/CMAKE_CUDA_ARCHITECTURES.html), although the default value is non-standard, [specified in `cuda.cmake`](https://github.com/catboost/catboost/blob/5fb7b9def07f4ea2df6dcc31b5cd1e81a8b00217/cmake/cuda.cmake#L7). The default value is intended to provide broad GPU compatibility and supported only when building with CUDA 11.8.
The most convenient way to override the default value is to use [`CUDAARCHS` environment variable](https://cmake.org/cmake/help/v3.24/envvar/CUDAARCHS.html).
{% endnote %}
```
python -m pip install --editable .
```
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
```
### Install from the source distribution
Builds in the process. So [build environment setup for CMake](https://catboost.ai/docs/en/installation/build-environment-setup-for-cmake.md) is required.
{% note info %}
If `CUDA_PATH` or `CUDA_ROOT` environment variable is defined and contains a path to a valid `CUDA` installation, then CatBoost python package will be built with this `CUDA` version.
Otherwise `CUDA` support will be disabled in the package.
{% endnote %}
{% note info %}
CUDA architectures to generate device code for are specified using [`CMAKE_CUDA_ARCHITECTURES` variable](https://cmake.org/cmake/help/v3.24/variable/CMAKE_CUDA_ARCHITECTURES.html), although the default value is non-standard, [specified in `cuda.cmake`](https://github.com/catboost/catboost/blob/5fb7b9def07f4ea2df6dcc31b5cd1e81a8b00217/cmake/cuda.cmake#L7). The default value is intended to provide broad GPU compatibility and supported only when building with CUDA 11.8.
The most convenient way to override the default value is to use [`CUDAARCHS` environment variable](https://cmake.org/cmake/help/v3.24/envvar/CUDAARCHS.html).
{% endnote %}
```
python -m pip install
```