Title: Improve installation DX: prebuilt wheels for 3.13/3.14/3.14t + declarative backend selection · Issue #2136 · abetlen/llama-cpp-python · GitHub
Open Graph Title: Improve installation DX: prebuilt wheels for 3.13/3.14/3.14t + declarative backend selection · Issue #2136 · abetlen/llama-cpp-python
X Title: Improve installation DX: prebuilt wheels for 3.13/3.14/3.14t + declarative backend selection · Issue #2136 · abetlen/llama-cpp-python
Description: Problem Installing llama-cpp-python with a GPU backend requires setting CMAKE_ARGS as an environment variable at build time: CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python This creates pain across the ecosystem: Not declarable...
Open Graph Description: Problem Installing llama-cpp-python with a GPU backend requires setting CMAKE_ARGS as an environment variable at build time: CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python This creates p...
X Description: Problem Installing llama-cpp-python with a GPU backend requires setting CMAKE_ARGS as an environment variable at build time: CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python This...
Opengraph URL: https://github.com/abetlen/llama-cpp-python/issues/2136
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Improve installation DX: prebuilt wheels for 3.13/3.14/3.14t + declarative backend selection","articleBody":"## Problem\n\nInstalling `llama-cpp-python` with a GPU backend requires setting `CMAKE_ARGS` as an environment variable at build time:\n\n```bash\nCMAKE_ARGS=\"-DGGML_METAL=on\" pip install llama-cpp-python\n```\n\nThis creates pain across the ecosystem:\n\n1. **Not declarable in `pyproject.toml`** — Every downstream project needs custom Makefiles or install scripts with GPU auto-detection logic (macOS → Metal, nvidia-smi → CUDA, rocminfo → ROCm, fallback → OpenBLAS). This is duplicated across hundreds of projects.\n\n2. **Cache invalidation is broken** — `pip` and `uv` cache wheels by package version, not by `CMAKE_ARGS`. A cached OpenBLAS wheel silently gets reused when Metal or CUDA is requested. Workaround: `--no-cache`, which defeats caching entirely.\n\n3. **GPU prebuilt wheels stop at Python 3.12** — The Metal wheel CI ([`build-wheels-metal.yaml`](https://github.com/abetlen/llama-cpp-python/blob/main/.github/workflows/build-wheels-metal.yaml)) is hardcoded to `CIBW_BUILD: \"cp39-* cp310-* cp311-* cp312-*\"`. The CUDA wheel CI ([`build-wheels-cuda.yaml`](https://github.com/abetlen/llama-cpp-python/blob/main/.github/workflows/build-wheels-cuda.yaml)) has its matrix pinned to Python 3.9-3.12. CPU-only wheels include 3.13 (via default cibuildwheel config in [`build-and-release.yaml`](https://github.com/abetlen/llama-cpp-python/blob/main/.github/workflows/build-and-release.yaml)), but the arm64 job there also pins to cp38-cp312. No workflow produces 3.14 or free-threaded (3.13t/3.14t) wheels. Python 3.13 has been stable since Oct 2024, 3.14 since Oct 2025. Free-threaded builds are increasingly important — vLLM, llguidance, and the broader no-GIL ecosystem depend on them.\n\nCurrent state of published wheel indexes:\n\n| Index | cp313 | cp314 | Free-threaded |\n|-------|-------|-------|---------------|\n| CPU (`/whl/cpu/`) | ✅ | ❌ | ❌ |\n| Metal (`/whl/metal/`) | ❌ | ❌ | ❌ |\n| CUDA (`/whl/cu1xx/`) | ❌ | ❌ | ❌ |\n\n## Proposed changes\n\n### 1. Expand prebuilt wheel matrix (highest impact, smallest change)\n\nUpdate `CIBW_BUILD` in Metal/CUDA workflows and add free-threaded support. This is the single highest-impact change — it eliminates source builds for most users.\n\n**`build-wheels-metal.yaml`:**\n\nUpgrade `cibuildwheel` from `v2.22.0` to `v3.x` ([3.0 added cp314/cp314t support](https://cibuildwheel.pypa.io/en/stable/changelog/)). In cibuildwheel 3.0, cp314t is built by default (free-threading is no longer experimental in 3.14), and cp313t requires `CIBW_ENABLE: cpython-freethreading`.\n\n```diff\n- uses: pypa/cibuildwheel@v2.22.0\n+ uses: pypa/cibuildwheel@v3.0.0\n env:\n- CIBW_BUILD: \"cp39-* cp310-* cp311-* cp312-*\"\n+ CIBW_BUILD: \"cp39-* cp310-* cp311-* cp312-* cp313-* cp314-*\"\n+ CIBW_ENABLE: cpython-freethreading\n```\n\n**`build-and-release.yaml`** — same cibuildwheel upgrade, and update the `build_wheels_arm64` job:\n\n```diff\n- CIBW_BUILD: \"cp38-* cp39-* cp310-* cp311-* cp312-*\"\n+ CIBW_BUILD: \"cp38-* cp39-* cp310-* cp311-* cp312-* cp313-* cp314-*\"\n+ CIBW_ENABLE: cpython-freethreading\n```\n\n**`build-wheels-cuda.yaml`** — uses a different build system (`python -m build --wheel` with a PowerShell matrix). The `pyver` matrix would need `\"3.13\", \"3.14\"` added.\n\nWith prebuilt wheels, any downstream project can use `uv`'s declarative index support:\n\n```toml\n# pyproject.toml — zero Makefile, zero CMAKE_ARGS\n[project]\ndependencies = [\"llama-cpp-python~=0.3\"]\n\n[tool.uv.sources]\nllama-cpp-python = [\n { index = \"llama-metal\", marker = \"sys_platform == 'darwin'\" },\n { index = \"llama-cpu\", marker = \"sys_platform == 'linux'\" },\n]\n\n[[tool.uv.index]]\nname = \"llama-metal\"\nurl = \"https://abetlen.github.io/llama-cpp-python/whl/metal\"\nexplicit = true\n\n[[tool.uv.index]]\nname = \"llama-cpu\"\nurl = \"https://abetlen.github.io/llama-cpp-python/whl/cpu\"\nexplicit = true\n```\n\n### 2. Document `--config-settings` as the source-build path\n\nSince the build backend is `scikit-build-core`, cmake args can be passed via the standard PEP 517 config-settings interface:\n\n```bash\npip install llama-cpp-python -C cmake.args=\"-DGGML_METAL=on\"\n# or with uv:\nuv pip install llama-cpp-python -C cmake.args=\"-DGGML_METAL=on\"\n```\n\nThis is cleaner than the `CMAKE_ARGS` env var — it's the standard PEP 517 mechanism, more explicit, and discoverable. It's already supported via scikit-build-core but not documented in the README or install docs.\n\n### 3. (Future) Adopt PEP 817 Wheel Variants\n\n[PEP 817](https://peps.python.org/pep-0817/) (draft, Dec 2025) introduces a standard mechanism for GPU/accelerator wheel variants. PyTorch 2.9 already ships experimental variant-enabled wheels. Once PEP 817 is accepted and tool support lands, `llama-cpp-python` could publish variant wheels that are auto-selected by the installer:\n\n```bash\n# Future: just works, installer picks Metal/CUDA/CPU automatically\npip install llama-cpp-python\n```\n\nThis is mentioned for context only — the actionable items are (1) and (2) above.\n\n## Ecosystem context\n\n- **Quansight offered funded engineering help** for free-threaded support in #2103 (via vLLM ecosystem work) — awaiting maintainer signal\n- **~470K monthly PyPI downloads** ([pypistats](https://pypistats.org/packages/llama-cpp-python)) — every project using this beyond toy scripts hits this install wall\n- **How others solved it:** PyTorch uses per-backend index URLs + PEP 817 variants; ONNX Runtime publishes separate PyPI packages per backend (`onnxruntime-gpu`, `onnxruntime-silicon`)\n\n## Related\n\n**Wheel matrix gaps (same root cause):**\n- #2103 — Pre-built wheels for Python 3.14 and 3.14 free-threaded\n- #2130 — Pre-built CPU-only wheel for Windows (cp313)\n- #2068 — Where can I download wheel for CUDA 12.8?\n- #2091 — CUDA 12.8 wheel request\n\n**Wheel variants / long-term packaging:**\n- #2092 — Add support for experimental wheel variants (wheelnext)\n- #1506 — Multi-arch support for pre-built CPU wheel (by @abetlen)\n- [Discussion #1875](https://github.com/abetlen/llama-cpp-python/discussions/1875) — Automating pre-building of wheels for all platforms\n\n**Downstream impact of missing wheels:**\n- #2118 — Installation deadlock on Hugging Face Spaces (musl/glibc mismatch)\n- #2113 — No working wheels for Debian/Ubuntu\n\nHappy to submit a PR for (1) and (2).","author":{"url":"https://github.com/clemlesne","@type":"Person","name":"clemlesne"},"datePublished":"2026-03-07T17:13:39Z","url":"https://github.com/abetlen/llama-cpp-python/issues/2136"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:c63d3c3a-0069-9ec3-654c-e8af6eb93523 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 9418:3EC783:2B47C5:38041C:6AFF97FD |
| html-safe-nonce | 08de1783d1e794b08071ec1454cdddf3b5d71bd1828db8d57df4b25b0c3a4165 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI5NDE4OjNFQzc4MzoyQjQ3QzU6MzgwNDFDOjZBRkY5N0ZEIiwidmlzaXRvcl9pZCI6IjU5OTQ4OTY0NzI4NzU3MDIyNjkiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | f0ef4304b47486016687fc223d0172f53257951c52886b67f089715de01868d0 |
| hovercard-subject-tag | issue:4038960837 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/abetlen/llama-cpp-python/2136/issue_layout |
| twitter:image | https://opengraph.githubassets.com/da22f406b23de731bd23b4a4598f0ef8593fe00edfcb3b115a7705b4f3e95399/abetlen/llama-cpp-python/issues/2136 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/da22f406b23de731bd23b4a4598f0ef8593fe00edfcb3b115a7705b4f3e95399/abetlen/llama-cpp-python/issues/2136 |
| og:image:alt | Problem Installing llama-cpp-python with a GPU backend requires setting CMAKE_ARGS as an environment variable at build time: CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python This creates p... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | clemlesne |
| hostname | github.com |
| expected-hostname | github.com |
| None | 2c75d045e8c84b51e2ac680086a6dd1eeaf2bc15b82137d22ee5106835d6256c |
| turbo-cache-control | no-preview |
| go-import | github.com/abetlen/llama-cpp-python git https://github.com/abetlen/llama-cpp-python.git |
| octolytics-dimension-user_id | 6826477 |
| octolytics-dimension-user_login | abetlen |
| octolytics-dimension-repository_id | 617868717 |
| octolytics-dimension-repository_nwo | abetlen/llama-cpp-python |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 617868717 |
| octolytics-dimension-repository_network_root_nwo | abetlen/llama-cpp-python |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 525b66d22c4f7e6bb8b62934bec198964f7e8b93 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width