Installation
Install PyPaimon in the Python environment used by your application. The base package supports Python 3.6 and newer; optional integrations have higher minimum versions. For the examples in this guide, use Python 3.10 or newer, or Python 3.11 or newer if you need Vortex.
Install the package
Create and activate a virtual environment. On macOS or Linux:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install pypaimon
On Windows, activate the environment with .venv\Scripts\activate instead.
The package includes the core catalog, table, Arrow, and pandas APIs, as well as
the paimon command. Core table reads and writes do not require a JVM or a
running Flink or Spark cluster.
Optional dependencies
Install only the extras needed by your workload. Quote package names containing brackets so shells such as zsh do not interpret them as filename patterns. The minimum versions below reflect this checkout's package requirements; dependency availability can also depend on the operating system.
| Workload | Install | Python requirement |
|---|---|---|
| Distributed Ray processing | python -m pip install 'pypaimon[ray]' | 3.8+ |
| Daft DataFrames | python -m pip install 'pypaimon[daft]' | 3.10+ |
| PyTorch datasets | python -m pip install 'pypaimon[torch]' | Must also satisfy the selected PyTorch version |
| SQL queries | python -m pip install 'pypaimon[sql]' | 3.10+ |
| Conditional merge expressions | python -m pip install 'pypaimon[datafusion]' | 3.10+ |
| HDF5 import | python -m pip install 'pypaimon[hdf5]' | 3.8+ |
| ROSBag import | python -m pip install 'pypaimon[rosbag]' | 3.10+ |
| LeRobot datasets | python -m pip install 'pypaimon[lerobot]' | 3.10+ |
| Mosaic files | python -m pip install 'pypaimon[mosaic]' | 3.9+ |
| Lance dataset export | python -m pip install 'pypaimon[lance]' | 3.10+ |
| Vortex files | python -m pip install 'pypaimon[vortex]' | 3.11+ |
| IVF-PQ vector indexes | python -m pip install 'pypaimon[vindex]' | 3.9+ |
| Full-text indexes | python -m pip install 'pypaimon[full-text]' | 3.8+ |
| Native HDFS access | python -m pip install 'pypaimon[hdfs]' | 3.10+, non-Windows |
Extras can be combined, for example:
python -m pip install 'pypaimon[daft,ray]'
For OSS access options, see Catalogs and Tables and PyJindoSDK. Parquet and the multimodal API's default file formats do not require a file-format extra.
Install from source
These docs describe the current source tree. A published package may not yet include every feature described here. From the repository root, install the Python module with:
python -m pip install ./paimon-python
For local Python development, use pip with dependency-group support to install the editable project and development tools together:
cd paimon-python
python -m pip install -e . --group dev
To produce a source archive and wheel, run from paimon-python/:
python -m pip install --group build
python -m build
The source archive and wheel are written to dist/ with the same version.
Development versions append the Git commit date, for example 2.2.dev20260927.
Install the wheel with python -m pip install dist/*.whl.
Optional OSS C++ backend
Native OSS reads require a pypaimon-rust build with storage-oss-cpp and
bridge discovery, plus pypaimon_oss_cpp on each worker. The library path is
detected automatically; set fs.oss.cpp.library.path only for a manually
installed bridge.
Set fs.oss.impl=cpp in the catalog and enable scan.native-plan.enabled and
read.native.enabled on the table. Python I/O uses Jindo by default, or set
fs.oss.python.impl=legacy. The C++ backend is read-only; use spawn, not
fork, for workers.
Verify the installation
python -c "from pypaimon import CatalogFactory, Schema; print('PyPaimon is ready')"
paimon --help
Continue with the Quick Start. Install compute or media extras in the worker environment as well when running distributed jobs.