Ship a linkable shared runtime and make the Python bindings use it

[shoumikhin]

Today pip install executorch gives you the Python side of ExecuTorch, but nothing a C++
program can link against. So if you want to write a small C++ app that loads and runs a
.pte model, you have to clone the repository, sync submodules, and build from source.

This change ships the runtime as a real shared library and exposes it through CMake, so the
wheel alone is enough.

What you get

Before, the wheel had everything welded into one Python extension file:

pip install executorch
  executorch/                  Python works
  _portable_lib.so   (~11 MB)  runtime + kernels + backends, all fused inside
  -> a C++ developer must build from source

After, the runtime is a separate library with a CMake package beside it:

pip install executorch
  executorch/lib/libexecutorch.so.1     the runtime, linkable
  executorch/include/                   the headers
  executorch/share/cmake/               so find_package works
  _portable_lib.so                      now depends on the runtime above

How you use it

Two lines in your build:

find_package(executorch REQUIRED)
target_link_libraries(my_app PRIVATE executorch::runtime)

And ordinary C++ in your program:

#include <executorch/extension/module/module.h>
#include <executorch/extension/tensor/tensor.h>
using namespace executorch::extension;

Module module("model.pte");
auto input = make_tensor_ptr({2, 4}, data.data());
auto result = module.forward(input);

Why the Python side changes too

executorch::runtime is an imported target whose location is worked out relative to the CMake
config file, so the package can be moved and no path from the build machine is baked in.

The Python extension has to move onto the same shared library in this change, not a later one.
Backends register themselves into one process-wide table when their library loads. If the
Python extension kept its own private copy of the runtime while a C++ app linked the new shared
one, a process using both would have two tables, and a backend registered in one would be
invisible to the other. Sharing the library is what keeps that single.

The shipped library is also the one the Python extension now depends on, which means the two
cannot drift apart: there is only one copy to load.

Tested

Built the wheel on Linux x86_64 and aarch64, installed it into a clean environment with no
source checkout reachable, then:

• compiled and ran the C++ example above against the installed wheel;
• confirmed exactly one backend registry across all shipped libraries, using symbol inspection;
• confirmed the Python extension resolves the registry through the shared library rather than a
  private copy;
• confirmed the CMake package still works after moving the installed directory, so nothing
  depends on an absolute path;
• ran the existing Python tests, including .pte execution and custom-operator compilation
  through the older CMake contract, so existing users are unaffected.

[shoumikhin]

Stack from ghstack (oldest at bottom):

• Check the shipped device code covers the GPUs a wheel claims #21567
• Publish CUDA wheels so a GPU user does not build from source #21569
• Ship the CUDA delegate as its own library #21531
• Ship the XNNPACK delegate as its own library #21526
• Ship the merged CPU kernels as their own library #21524
• Ship the thread pool as its own library so a process has one pool #21522
• -> Ship a linkable shared runtime and make the Python bindings use it #21514

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/21514

• 📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❌ 28 New Failures, 175 Pending, 2 Unrelated Failures

As of commit bb1959c with merge base 6bbb75a ():

NEW FAILURES - The following jobs have failed:

• Build Presets / windows (pybind) / build (gh)
• Build Presets / windows (windows) / build (gh)
• pull / test-arm-backend-public-api-backward-compatibility / linux-job (gh)
  RuntimeError: Command docker exec -t c260ce8e27019ea96c42b5b96998a687c7487448ba41d518d1c80a61241f520b /exec failed with exit code 1
• pull / test-lora-linux / linux-job (gh)
  AttributeError: '_OpNamespace' 'llama' object has no attribute 'sdpa_with_kv_cache'
• pull / test-lora-multimethod-linux / linux-job (gh)
  AttributeError: '_OpNamespace' 'llama' object has no attribute 'sdpa_with_kv_cache'
• pull / test-models-linux (emformer_join, xnnpack-quantization-delegation, linux.4xlarge.memory) / linux-job (gh)
  RuntimeError: Command docker exec -t 984d7d9fa36fc679cbba87fc35305b718daa4c4df8ca55944d5b379bd670eed9 /exec failed with exit code 1
• pull / test-models-linux (ic4, xnnpack-quantization-delegation, linux.4xlarge.memory) / linux-job (gh)
  RuntimeError: Command docker exec -t 6420037222f0257ef2766d3746f1e924d4cb8c6d30d4d76469188e54b682675d /exec failed with exit code 1
• pull / test-multimodal-linux (gemma3-4b) / linux-job (gh)
  RuntimeError: Command docker exec -t 3354ab73f6706e37a1b76c11cdfcd1974533fc0540af18438d4dffcc1032601e /exec failed with exit code 1
• pull / test-phi-3-mini-runner-linux / linux-job (gh)
  AttributeError: '_OpNamespace' 'llama' object has no attribute 'sdpa_with_kv_cache'
• pull / unittest / linux / linux-job (gh)
  backends/xnnpack/test/passes/test_channels_last_tagged_reshape.py::TestChannelsLastTaggedReshapePass::test_conv_linear_dim_order_swaps
• pull / unittest-editable / linux / linux-job (gh)
  backends/xnnpack/test/passes/test_channels_last_tagged_reshape.py::TestChannelsLastTaggedReshapePass::test_conv_linear_dim_order_swaps
• Test WebGPU Native (Dawn) / test-webgpu-native / linux-job (gh)
  [ FAILED ] WebGPUNative.SdpaAllFamiliesRanWhenDirSet
• trunk / test-arm-backend-ethos-u (test_deit_e2e_ethos_u) / linux-job (gh)
  RuntimeError: Command docker exec -t 47e6331a865006df7c585d172043c3aa81a06ed0ae675182bf50a36eae2d52c1 /exec failed with exit code 1
• trunk / test-arm-backend-ethos-u (test_model_smollm2_135M_ethos_u85) / linux-job (gh)
  RuntimeError: Command docker exec -t 8bba15420ca80f1dc07e2dabdf73a4599a6e4d7d627fd1c3159b77b4cabead5b /exec failed with exit code 1
• trunk / test-arm-backend-ethos-u (test_ootb_tests_ethos_u) / linux-job (gh)
  RuntimeError: Command docker exec -t 26729164b3da03391cb382544c97236ff85392ec230f6693b9bf19c6504b1501 /exec failed with exit code 1
• trunk / test-arm-backend-ethos-u (test_ootb_tests_tosa) / linux-job (gh)
  RuntimeError: Command docker exec -t b14408aa96306954be168118049d53be61bc2659d3787785845b611dc4211f0b /exec failed with exit code 1
• trunk / test-arm-backend-ethos-u (test_pytest_models_ethos_u55) / linux-job (gh)
  RuntimeError: Command docker exec -t 49b79453bc1072abab1f57d111c8fa7a83df5ef1370aa57691b63f4f01875c81 /exec failed with exit code 1
• trunk / test-arm-backend-ethos-u (test_pytest_models_ethos_u85) / linux-job (gh)
  RuntimeError: Command docker exec -t 1dacf3f9204c24bc95d0f300a673d920f1adc1b7bd80a39433d79dcdba48dbfb /exec failed with exit code 1
• trunk / test-arm-backend-ethos-u (test_pytest_ops_ethos_u55) / linux-job (gh)
  RuntimeError: Command docker exec -t a80a43b4430f4b02ab3727e29b2370944e90c7c703def868ff2ae7fcbb45e11d /exec failed with exit code 1
• trunk / test-arm-backend-vkml (test_pytest_models_vkml) / linux-job (gh)
  RuntimeError: Command docker exec -t d3c732cf933dba171ac9865c109bd04fd02c8f9dde4d59e6adedda102d51c100 /exec failed with exit code 1
• trunk / test-arm-backend-vkml (test_pytest_ops_vkml) / linux-job (gh)
  RuntimeError: Command docker exec -t eaa6f6e98e20a435b4ce66144d4306374c0de01d6914de3ac7054bf1d71fb95f /exec failed with exit code 1
• trunk / test-huggingface-transformers-xnnpack (gemma3-1b|xnnpack|--quantize) / linux-job (gh)
  RuntimeError: Command docker exec -t ff430ab2c9c4ef1025e6b463470db332ed89b33ea4de9f292b905e8d9d312f0a /exec failed with exit code 1
• trunk / test-huggingface-transformers-xnnpack (llama3.2-1b|xnnpack|--quantize) / linux-job (gh)
  RuntimeError: Command docker exec -t c8e1266473e903f0a0098929c4d6896012e18ce7cc453e05d5b1d2ac8d1b6a22 /exec failed with exit code 1
• trunk / test-huggingface-transformers-xnnpack (qwen3-0.6b|xnnpack|--quantize) / linux-job (gh)
  RuntimeError: Command docker exec -t 5f3bf46811b609bcb4daf0960ddb48476363708a2d45bfa3e369389001d3b721 /exec failed with exit code 1
• trunk / test-huggingface-transformers-xnnpack (qwen3-1.7b|xnnpack|--quantize) / linux-job (gh)
  RuntimeError: Command docker exec -t 2ec68df7f08c0e73e1ff187cd18441288ce5594e94de0a3088912b4bf3852458 /exec failed with exit code 1
• trunk / test-huggingface-transformers-xnnpack (smollm2-135m|xnnpack|--quantize) / linux-job (gh)
  RuntimeError: Command docker exec -t dc230dd263326f0a804dad73283610464cc2be040155e0a5384fc56da519d739 /exec failed with exit code 1
• trunk / test-huggingface-transformers-xnnpack (smollm3-3b|xnnpack|--quantize) / linux-job (gh)
  RuntimeError: Command docker exec -t a27eb78f08ef64f7d349a19fda37f81ec49d73741eb75235f5a01f70b7db0d87 /exec failed with exit code 1
• trunk / unittest-release / linux / linux-job (gh)
  backends/xnnpack/test/passes/test_channels_last_tagged_reshape.py::TestChannelsLastTaggedReshapePass::test_conv_linear_dim_order_swaps

FLAKY - The following job failed but was likely due to flakiness present on trunk:

• pull / unittest-editable / windows / windows-job (gh) (detected as infra flaky with no log or failing log classifier)

BROKEN TRUNK - The following job failed but was present on the merge base:

👉 Rebase onto the `viable/strict` branch to avoid these failures

• trunk / test-arm-backend-ethos-u (test_pytest_ops_ethos_u85) / linux-job (gh) (trunk failure)

This comment was automatically generated by Dr. CI and updates every 15 minutes.

[github-actions]

This PR needs a release notes: label

If your change should be included in the release notes (i.e. would users of this library care about this change?), please use a label starting with release notes:. This helps us keep track and include your important work in the next release notes.

To add a label, you can comment to pytorchbot, for example
@pytorchbot label "release notes: none"

For more information, see
https://github.com/pytorch/pytorch/wiki/PyTorch-AutoLabel-Bot#why-categorize-for-release-notes-and-how-does-it-work.

[Copilot]

🟡 Not ready to approve

The new shared-runtime linking logic uses GNU ld-specific flags without platform guards, which can break builds when EXECUTORCH_BUILD_SHARED is enabled on non-ELF toolchains.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

This PR makes the ExecuTorch wheel usable as a C++ SDK by shipping a linkable shared runtime (libexecutorch.so) and exposing it via find_package(executorch) as executorch::runtime, while also updating the Python extensions to link against that shared runtime to preserve a single process-wide backend registry.

Changes:

• Add a consolidated shared runtime target (executorch_shared / libexecutorch.so) and update multiple extension/tool targets to resolve runtime symbols from it.
• Extend the wheel CMake package config to provide an imported target executorch::runtime resolved relative to the installed wheel for relocatable consumption.
• Add CI wheel smoke coverage that verifies single-registry behavior and that a standalone C++ app can build/run via only find_package(executorch) + executorch::runtime.

File summaries

File	Description
tools/cmake/Utils.cmake	Adds helper to force linking against the shared runtime early on the link line.
tools/cmake/preset/pybind.cmake	Enables EXECUTORCH_BUILD_SHARED for the Linux pybind preset to ship the shared runtime in wheels.
tools/cmake/executorch-wheel-config.cmake	Exposes executorch::runtime imported target and keeps legacy _portable_lib discovery.
tools/cmake/Codegen.cmake	Avoids linking executorch_core when shared runtime is enabled; forces shared runtime resolution.
setup.py	Installs the shared runtime SONAME into the wheel and expands header install coverage for runtime-linked extensions.
kernels/quantized/CMakeLists.txt	Adds wheel-runtime-relative RPATH when shared runtime is enabled.
extension/training/CMakeLists.txt	Switches pybind training module to shared runtime path and fixes RPATH for wheel layout.
extension/llm/runner/CMakeLists.txt	Forces shared runtime resolution and adjusts RPATH when shared runtime is enabled.
extension/llm/custom_ops/CMakeLists.txt	Ensures wheel-built artifact has correct RPATH and resolves runtime from shared library.
devtools/etdump/CMakeLists.txt	Avoids executorch whole-archive when shared runtime is present; links shared runtime instead.
devtools/bundled_program/CMakeLists.txt	Avoids whole-archive duplication by linking shared runtime when enabled.
codegen/tools/CMakeLists.txt	Makes selective_build resolve runtime via shared library and sets wheel-relative RPATH.
CMakeLists.txt	Defines executorch_shared earlier and updates pybind/utility targets to avoid embedding duplicate registries.
.github/workflows/build-wheels-*.yml	Expands workflow path triggers to include CMakeLists and tools/cmake/.
.ci/scripts/wheel/test_linux.py	Runs the new C++ SDK wheel test as part of Linux wheel smoke tests.
.ci/scripts/wheel/test_linux_aarch64.py	Runs the new C++ SDK wheel test as part of aarch64 Linux wheel smoke tests.
.ci/scripts/wheel/test_cpp_sdk.py	New test that validates single-registry and that a standalone C++ app can link/run via the wheel.

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 2
• Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[shoumikhin]

Good catch, fixed in the latest push.

Both of these were real. The whole-archive loop used to go through
$<LINK_LIBRARY:WHOLE_ARCHIVE,...>, which CMake maps to the right flag per
platform, and switching to raw flags lost that. There is now a small
executorch_target_whole_archive helper next to the existing kernel-link helpers
that picks --whole-archive, -force_load, or /WHOLEARCHIVE based on the
platform, and the shared-runtime helper only adds --no-as-needed on ELF
platforms. No raw GNU flag is emitted outside those two helpers now.

Worth noting the option that reaches this code is only turned on for Linux today,
so this is about not breaking someone who enables it by hand rather than a live
failure. Verified by building the wheel and running the wheel checks on Linux
x86_64 and aarch64 after the change.

[Copilot]

🟡 Not ready to approve

The new executorch::runtime CMake config has correctness/robustness issues (duplicate target definition risk and unconditional Python failure path) that can break consumers during configuration.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (3)

tools/cmake/executorch-wheel-config.cmake:121

• With the new executorch::runtime target, a pure C++ consumer should be able to configure successfully even if python3 isn't available on PATH. Right now the unconditional execute_process(${PYTHON_EXECUTABLE} ...) followed by FATAL_ERROR prevents using the shared runtime without Python. Consider treating EXT_SUFFIX lookup as best-effort when the shared runtime was found, and skip _portable_lib discovery in that case.

find_library(
  _portable_lib_LIBRARY
  NAMES _portable_lib${EXT_SUFFIX}
  PATHS "${_executorch_package_root}/extension/pybindings/"
)

tools/cmake/executorch-wheel-config.cmake:121

• find_library() will also search default system locations, which can accidentally pick up a different _portable_lib<EXT_SUFFIX> (e.g., from another install) and silently mix headers/libs. Since this config is meant to bind to the wheel it lives in, add NO_DEFAULT_PATH to restrict the search to the wheel directory.

find_library(
  _portable_lib_LIBRARY
  NAMES _portable_lib${EXT_SUFFIX}
  PATHS "${_executorch_package_root}/extension/pybindings/"
)

tools/cmake/executorch-wheel-config.cmake:68

• executorch-config.cmake can be processed more than once in a single configure (e.g., multiple find_package(executorch) calls via subprojects). Unconditionally calling add_library(executorch::runtime ...) will then error with a duplicate target name. Guard the add_library call with if(NOT TARGET executorch::runtime) but still apply the target properties afterward.

This issue also appears in the following locations of the same file:

• line 117
• line 117

  add_library(executorch::runtime SHARED IMPORTED)
  set_target_properties(
    executorch::runtime
    PROPERTIES IMPORTED_LOCATION "${_executorch_runtime_library}"
               INTERFACE_INCLUDE_DIRECTORIES "${EXECUTORCH_INCLUDE_DIRS}"

• Files reviewed: 20/20 changed files
• Comments generated: 0 new
• Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.