feat: Python bindings via PyO3 + Cargo workspace restructure
enhancementpriority: medium
### Search before asking
- [x] I have searched the Ultralytics [issues](https://github.com/ultralytics/PROJECT_NAME/issues) and found no similar feature requests.
### Description
Add official Python bindings to `ultralytics-inference` via PyO3, delivered as a Cargo workspace restructure. The repo splits into two crates — `crates/ultralytics-inference` (existing library + CLI, unchanged) and `crates/ultralytics-pyo3` (new `cdylib` extension) — plus a `py-inference/` Python package built with maturin. A `cdylib` crate-type cannot coexist with `rlib`/`bin` in the same package, making the workspace restructure a technical requirement, not an optional refactor.
### Use case
Python is the dominant language in the computer-vision ecosystem and Ultralytics' primary audience. Today, Python users who want the performance of this Rust inference engine have no official path: they must either shell out to the CLI or reimplement the pipeline in Python. Native bindings close that gap with a clean, Pythonic API:
```python
from ultralytics_inference import YOLO
model = YOLO("yolo11n.onnx")
results = model.predict("https://ultralytics.com/images/bus.jpg", conf=0.25, imgsz=640)
# also works with files, directories, globs, and batch lists
results = model.predict("images/*.jpg", conf=0.5, save=True)
results = model.predict(["img1.jpg", "img2.jpg"])
```
The workspace layout also future-proofs the repo for Node.js and WebAssembly support: a single `crates/ultralytics-napi` member using [napi-rs](https://napi.rs) would cover both targets (napi-rs supports native Node.js addons and `wasm32` from one crate) without touching the core library.
### Additional
A working implementation is ready as a draft PR. It includes:
- Zero breaking changes to the existing Rust public API
- Single version bump point via `[workspace.package]`
- `[workspace.lints]` enforcing `clippy::pedantic` + `missing_docs` across all members
- `.pyi` stubs via `maturin generate-stubs` for IDE type support
- Rust integration tests for the pyo3 crate (no Python interpreter required)
- Python unit tests via pytest with a conftest stub (run without a compiled extension)
Happy to iterate on the design before the PR is opened if the team has preferences around the API surface or packaging approach.
### Are you willing to submit a PR?
- [x] Yes I'd like to help by submitting a PR!
关闭于 2026-05-11 2 条评论