From 0b3c22fca6106e01380882e372ed9767efb6e71a Mon Sep 17 00:00:00 2001 From: Zuby Afzal Date: Mon, 28 Apr 2025 20:39:05 -0700 Subject: [PATCH 1/8] Update docs for intel-macOS systems and building from source --- README.md | 2 +- docs/source/backends-xnnpack.md | 2 +- docs/source/getting-started.md | 5 +++-- docs/source/using-executorch-building-from-source.md | 12 ++++++++++-- docs/source/using-executorch-ios.md | 9 ++++++++- 5 files changed, 23 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 22a6290e472..8003b25b17b 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ It supports a wide range of models including LLMs (Large Language Models), CV (C Platform Support: - Operating Systems: - iOS - - Mac + - MacOS (ARM64) - Android - Linux - Microcontrollers diff --git a/docs/source/backends-xnnpack.md b/docs/source/backends-xnnpack.md index 46ab379f186..b6bd1eab7c6 100644 --- a/docs/source/backends-xnnpack.md +++ b/docs/source/backends-xnnpack.md @@ -14,7 +14,7 @@ The XNNPACK delegate is the ExecuTorch solution for CPU execution on mobile CPUs - ARM64 on Android, iOS, macOS, Linux, and Windows. - ARMv7 (with NEON) on Android. - ARMv6 (with VFPv2) on Linux. -- x86 and x86-64 (up to AVX512) on Windows, Linux, macOS, Android, and iOS simulator. +- x86 and x86-64 (up to AVX512) on Windows, Linux, Android. ## Development Requirements diff --git a/docs/source/getting-started.md b/docs/source/getting-started.md index b7a97190b49..be15e7d6ea2 100644 --- a/docs/source/getting-started.md +++ b/docs/source/getting-started.md @@ -10,8 +10,9 @@ The following are required to install the ExecuTorch host libraries, needed to e - Python 3.10 - 3.12 - g++ version 7 or higher, clang++ version 5 or higher, or another C++17-compatible toolchain. -- Linux or MacOS operating system (Arm or x86). - - Windows is supported via WSL. +- Linux (x86_64 or ARM64) or macOS (ARM64). + - Intel-based macOS systems require building PyTorch from source (see [Building From Source](using-executorch-building-from-source.md) for instructions). + - Windows is supported via WSL. ## Installation To use ExecuTorch, you will need to install both the Python package and the appropriate platform-specific runtime libraries. Pip is the recommended way to install the ExecuTorch python package. diff --git a/docs/source/using-executorch-building-from-source.md b/docs/source/using-executorch-building-from-source.md index f3aac4024af..67065c64f63 100644 --- a/docs/source/using-executorch-building-from-source.md +++ b/docs/source/using-executorch-building-from-source.md @@ -16,7 +16,7 @@ Linux (x86_64) - Ubuntu 20.04.6 LTS+ - RHEL 8+ -macOS (x86_64/M1/M2) +macOS (x86_64/ARM64) - Big Sur (11.0)+ Windows (x86_64) @@ -56,13 +56,21 @@ Or alternatively, [install conda on your machine](https://conda.io/projects/cond conda create -yn executorch python=3.10.0 && conda activate executorch ``` -## Install ExecuTorch pip package from Source +## Install ExecuTorch pip package from source ```bash # Install ExecuTorch pip package and its dependencies, as well as # development tools like CMake. # If developing on a Mac, make sure to install the Xcode Command Line Tools first. + # Intel-based macOS systems require building PyTorch from source (see below) ./install_executorch.sh ``` + + Use the [`--use-pt-pinned-commit` flag](https://github.com/pytorch/executorch/blob/main/install_executorch.sh) to install Executorch with an existing PyTorch build. + See the [PyTorch instructions](https://github.com/pytorch/pytorch#installation) on how to build PyTorch from source. + + ```bash + ./install_executorch.sh --use-pt-pinned-commit + ``` Not all backends are built into the pip wheel by default. You can link these missing/experimental backends by turning on the corresponding cmake flag. For example, to include the MPS backend: diff --git a/docs/source/using-executorch-ios.md b/docs/source/using-executorch-ios.md index 508669112f1..11b40435d4e 100644 --- a/docs/source/using-executorch-ios.md +++ b/docs/source/using-executorch-ios.md @@ -4,7 +4,7 @@ ExecuTorch supports both iOS and macOS via Objective-C, Swift, and C++. ExecuTor ## Integration -The ExecuTorch Runtime for iOS and macOS is distributed as a collection of prebuilt [.xcframework](https://developer.apple.com/documentation/xcode/creating-a-multi-platform-binary-framework-bundle) binary targets. These targets are compatible with both iOS and macOS devices and simulators and are available in both release and debug modes: +The ExecuTorch Runtime for iOS and macOS (ARM64) is distributed as a collection of prebuilt [.xcframework](https://developer.apple.com/documentation/xcode/creating-a-multi-platform-binary-framework-bundle) binary targets. These targets are compatible with both iOS and macOS devices and simulators and are available in both release and debug modes: * `executorch` - Main Runtime components * `backend_coreml` - Core ML backend @@ -114,6 +114,13 @@ python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip ./backends/apple/coreml/scripts/install_requirements.sh ``` +- **Intel-based macOS** systems require building PyTorch from source: + - Use the [`--use-pt-pinned-commit` flag](https://github.com/pytorch/executorch/blob/main/install_requirements.sh) to install Executorch with an existing PyTorch build. + See the [PyTorch instructions](https://github.com/pytorch/pytorch#installation) on how to build PyTorch from source. + ```bash + ./install_requirements.sh --use-pt-pinned-commit + ``` + 5. Install [CMake](https://cmake.org): Download the macOS binary distribution from the [CMake website](https://cmake.org/download), open the `.dmg` file, move `CMake.app` to the `/Applications` directory, and then run the following command to install the CMake command-line tools: From e5a4e67d933a7b8ffd726b8d174b3b923ef8a6ee Mon Sep 17 00:00:00 2001 From: Zuby Afzal Date: Mon, 28 Apr 2025 20:39:48 -0700 Subject: [PATCH 2/8] Add intel-macOS system check --- install_requirements.py | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/install_requirements.py b/install_requirements.py index 7d923672009..92e637c1897 100644 --- a/install_requirements.py +++ b/install_requirements.py @@ -75,6 +75,10 @@ def python_is_compatible(): def install_requirements(use_pytorch_nightly): + # Prevent pip install on Intel-based macOS systems (no prebuilt PyTorch binaries available). + if use_pytorch_nightly and is_intel_mac_os(): + sys.exit(1) + # pip packages needed by exir. TORCH_PACKAGE = [ # Setting use_pytorch_nightly to false to test the pinned PyTorch commit. Note @@ -163,6 +167,24 @@ def install_optional_example_requirements(use_pytorch_nightly): ) +# Prebuilt binaries for Intel-based macOS are no longer available on PyPI; users must compile from source. +# PyTorch stopped building macOS x86_64 binaries since version 2.3.0 (January 2024). +def is_intel_mac_os(): + # Returns True if running on Intel-based macOS + if platform.system().lower() == "darwin" and platform.machine().lower() in ( + "x86", + "x86_64", + "i386", + ): + print( + "ERROR: Prebuilt PyTorch binaries are no longer available for Intel-based macOS.\n" + "Please compile from source by following https://pytorch.org/executorch/0.6/using-executorch-building-from-source.html", + file=sys.stderr, + ) + return True + return False + + def main(args): parser = argparse.ArgumentParser() parser.add_argument( From b7655f7261a66b392be574f8ec9882ff11de72e2 Mon Sep 17 00:00:00 2001 From: Zuby Afzal Date: Thu, 1 May 2025 21:32:59 -0700 Subject: [PATCH 3/8] Update pip install commands for intel macOS systems and pytorch versions built from source --- install_requirements.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/install_requirements.py b/install_requirements.py index 92e637c1897..ef039107db3 100644 --- a/install_requirements.py +++ b/install_requirements.py @@ -170,15 +170,15 @@ def install_optional_example_requirements(use_pytorch_nightly): # Prebuilt binaries for Intel-based macOS are no longer available on PyPI; users must compile from source. # PyTorch stopped building macOS x86_64 binaries since version 2.3.0 (January 2024). def is_intel_mac_os(): - # Returns True if running on Intel-based macOS + # Returns True if running on Intel macOS if platform.system().lower() == "darwin" and platform.machine().lower() in ( "x86", "x86_64", "i386", ): print( - "ERROR: Prebuilt PyTorch binaries are no longer available for Intel-based macOS.\n" - "Please compile from source by following https://pytorch.org/executorch/0.6/using-executorch-building-from-source.html", + "ERROR: Prebuilt PyTorch wheels are no longer available for Intel-based macOS.\n" + "Please build from source by following https://docs.pytorch.org/executorch/main/using-executorch-building-from-source.html", file=sys.stderr, ) return True From 695c782b820452399fa74def10df29a7b47b9196 Mon Sep 17 00:00:00 2001 From: Zuby Afzal Date: Thu, 1 May 2025 21:42:06 -0700 Subject: [PATCH 4/8] Update building from source docs --- docs/source/using-executorch-building-from-source.md | 2 +- docs/source/using-executorch-ios.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/using-executorch-building-from-source.md b/docs/source/using-executorch-building-from-source.md index 67065c64f63..f93eaed321a 100644 --- a/docs/source/using-executorch-building-from-source.md +++ b/docs/source/using-executorch-building-from-source.md @@ -61,7 +61,7 @@ Or alternatively, [install conda on your machine](https://conda.io/projects/cond # Install ExecuTorch pip package and its dependencies, as well as # development tools like CMake. # If developing on a Mac, make sure to install the Xcode Command Line Tools first. - # Intel-based macOS systems require building PyTorch from source (see below) + # Intel-based macOS systems require building PyTorch, Torchvision, and Torchaudio from source (see below) ./install_executorch.sh ``` diff --git a/docs/source/using-executorch-ios.md b/docs/source/using-executorch-ios.md index 11b40435d4e..550ce0e655e 100644 --- a/docs/source/using-executorch-ios.md +++ b/docs/source/using-executorch-ios.md @@ -114,7 +114,7 @@ python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip ./backends/apple/coreml/scripts/install_requirements.sh ``` -- **Intel-based macOS** systems require building PyTorch from source: +- **Intel-based macOS** systems require building PyTorch, Torchvision, and Torchaudio from source: - Use the [`--use-pt-pinned-commit` flag](https://github.com/pytorch/executorch/blob/main/install_requirements.sh) to install Executorch with an existing PyTorch build. See the [PyTorch instructions](https://github.com/pytorch/pytorch#installation) on how to build PyTorch from source. ```bash From a47238b8635da457a56cdbb38104d82072d81f43 Mon Sep 17 00:00:00 2001 From: Zuby Afzal Date: Mon, 12 May 2025 16:32:48 -0700 Subject: [PATCH 5/8] Restore fallback installs for audio and vision; move print statement; update docs url --- install_requirements.py | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/install_requirements.py b/install_requirements.py index ef039107db3..3ce9ebac178 100644 --- a/install_requirements.py +++ b/install_requirements.py @@ -75,8 +75,13 @@ def python_is_compatible(): def install_requirements(use_pytorch_nightly): - # Prevent pip install on Intel-based macOS systems (no prebuilt PyTorch binaries available). + # Skip pip install on Intel macOS if using nightly. if use_pytorch_nightly and is_intel_mac_os(): + print( + "ERROR: Prebuilt PyTorch wheels are no longer available for Intel-based macOS.\n" + "Please build from source by following https://docs.pytorch.org/executorch/main/using-executorch-building-from-source.html", + file=sys.stderr, + ) sys.exit(1) # pip packages needed by exir. @@ -171,18 +176,12 @@ def install_optional_example_requirements(use_pytorch_nightly): # PyTorch stopped building macOS x86_64 binaries since version 2.3.0 (January 2024). def is_intel_mac_os(): # Returns True if running on Intel macOS - if platform.system().lower() == "darwin" and platform.machine().lower() in ( + return platform.system().lower() == "darwin" and platform.machine().lower() in ( "x86", "x86_64", "i386", - ): - print( - "ERROR: Prebuilt PyTorch wheels are no longer available for Intel-based macOS.\n" - "Please build from source by following https://docs.pytorch.org/executorch/main/using-executorch-building-from-source.html", - file=sys.stderr, - ) - return True - return False + ) + def main(args): From ce62ba9920946224abb5ca2bd29fc3e70c489075 Mon Sep 17 00:00:00 2001 From: Zuby Afzal Date: Mon, 16 Jun 2025 19:13:03 -0700 Subject: [PATCH 6/8] Update Intel macOS install instructions in doc --- docs/source/using-executorch-ios.md | 4 ++-- install_requirements.py | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/using-executorch-ios.md b/docs/source/using-executorch-ios.md index 550ce0e655e..a80ec5bfad7 100644 --- a/docs/source/using-executorch-ios.md +++ b/docs/source/using-executorch-ios.md @@ -115,10 +115,10 @@ python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip ``` - **Intel-based macOS** systems require building PyTorch, Torchvision, and Torchaudio from source: - - Use the [`--use-pt-pinned-commit` flag](https://github.com/pytorch/executorch/blob/main/install_requirements.sh) to install Executorch with an existing PyTorch build. + - Use the [`--use-pt-pinned-commit --minimal` flags](https://github.com/pytorch/executorch/blob/main/install_executorch.py) to install Executorch with an existing PyTorch build. See the [PyTorch instructions](https://github.com/pytorch/pytorch#installation) on how to build PyTorch from source. ```bash - ./install_requirements.sh --use-pt-pinned-commit + ./install_executorch.sh --use-pt-pinned-commit --minimal ``` 5. Install [CMake](https://cmake.org): diff --git a/install_requirements.py b/install_requirements.py index 3ce9ebac178..2ac5a34934b 100644 --- a/install_requirements.py +++ b/install_requirements.py @@ -183,7 +183,6 @@ def is_intel_mac_os(): ) - def main(args): parser = argparse.ArgumentParser() parser.add_argument( From 53b16bde3e01c01ecebd3a34c7c9daf3a192aa76 Mon Sep 17 00:00:00 2001 From: Zuby Afzal Date: Tue, 17 Jun 2025 15:58:09 -0700 Subject: [PATCH 7/8] Consolidate Intel-macOS instructions into building-from-source --- docs/source/using-executorch-building-from-source.md | 10 ++++++++-- docs/source/using-executorch-ios.md | 7 ------- install_requirements.py | 2 +- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/source/using-executorch-building-from-source.md b/docs/source/using-executorch-building-from-source.md index f93eaed321a..5d70fb33a9e 100644 --- a/docs/source/using-executorch-building-from-source.md +++ b/docs/source/using-executorch-building-from-source.md @@ -65,13 +65,19 @@ Or alternatively, [install conda on your machine](https://conda.io/projects/cond ./install_executorch.sh ``` - Use the [`--use-pt-pinned-commit` flag](https://github.com/pytorch/executorch/blob/main/install_executorch.sh) to install Executorch with an existing PyTorch build. - See the [PyTorch instructions](https://github.com/pytorch/pytorch#installation) on how to build PyTorch from source. + See the [PyTorch instructions](https://github.com/pytorch/pytorch#installation) on how to build PyTorch from source. + + Use the [`--use-pt-pinned-commit` flag](../../install_executorch.py) to install ExecuTorch with an existing PyTorch build: ```bash ./install_executorch.sh --use-pt-pinned-commit ``` + For Intel-based macOS systems, use the [`--use-pt-pinned-commit --minimal` flags](../../install_executorch.py): + ```bash + ./install_executorch.sh --use-pt-pinned-commit --minimal + ``` + Not all backends are built into the pip wheel by default. You can link these missing/experimental backends by turning on the corresponding cmake flag. For example, to include the MPS backend: ```bash diff --git a/docs/source/using-executorch-ios.md b/docs/source/using-executorch-ios.md index a80ec5bfad7..e3668a29e33 100644 --- a/docs/source/using-executorch-ios.md +++ b/docs/source/using-executorch-ios.md @@ -114,13 +114,6 @@ python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip ./backends/apple/coreml/scripts/install_requirements.sh ``` -- **Intel-based macOS** systems require building PyTorch, Torchvision, and Torchaudio from source: - - Use the [`--use-pt-pinned-commit --minimal` flags](https://github.com/pytorch/executorch/blob/main/install_executorch.py) to install Executorch with an existing PyTorch build. - See the [PyTorch instructions](https://github.com/pytorch/pytorch#installation) on how to build PyTorch from source. - ```bash - ./install_executorch.sh --use-pt-pinned-commit --minimal - ``` - 5. Install [CMake](https://cmake.org): Download the macOS binary distribution from the [CMake website](https://cmake.org/download), open the `.dmg` file, move `CMake.app` to the `/Applications` directory, and then run the following command to install the CMake command-line tools: diff --git a/install_requirements.py b/install_requirements.py index 2ac5a34934b..66768426a99 100644 --- a/install_requirements.py +++ b/install_requirements.py @@ -175,7 +175,7 @@ def install_optional_example_requirements(use_pytorch_nightly): # Prebuilt binaries for Intel-based macOS are no longer available on PyPI; users must compile from source. # PyTorch stopped building macOS x86_64 binaries since version 2.3.0 (January 2024). def is_intel_mac_os(): - # Returns True if running on Intel macOS + # Returns True if running on Intel macOS. return platform.system().lower() == "darwin" and platform.machine().lower() in ( "x86", "x86_64", From df9c97af1cd67caad122df5f11c184d36883f2d2 Mon Sep 17 00:00:00 2001 From: Zuby Afzal Date: Tue, 17 Jun 2025 16:16:47 -0700 Subject: [PATCH 8/8] Remove Torchvision and Torchaudio references in Intel instructions --- .../using-executorch-building-from-source.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/source/using-executorch-building-from-source.md b/docs/source/using-executorch-building-from-source.md index 5d70fb33a9e..7680e7bb743 100644 --- a/docs/source/using-executorch-building-from-source.md +++ b/docs/source/using-executorch-building-from-source.md @@ -61,22 +61,22 @@ Or alternatively, [install conda on your machine](https://conda.io/projects/cond # Install ExecuTorch pip package and its dependencies, as well as # development tools like CMake. # If developing on a Mac, make sure to install the Xcode Command Line Tools first. - # Intel-based macOS systems require building PyTorch, Torchvision, and Torchaudio from source (see below) + # Intel-based macOS systems require building PyTorch from source (see below) ./install_executorch.sh ``` - See the [PyTorch instructions](https://github.com/pytorch/pytorch#installation) on how to build PyTorch from source. + See the [PyTorch instructions](https://github.com/pytorch/pytorch#installation) on how to build PyTorch from source. - Use the [`--use-pt-pinned-commit` flag](../../install_executorch.py) to install ExecuTorch with an existing PyTorch build: + Use the [`--use-pt-pinned-commit` flag](../../install_executorch.py) to install ExecuTorch with an existing PyTorch build: ```bash ./install_executorch.sh --use-pt-pinned-commit ``` - For Intel-based macOS systems, use the [`--use-pt-pinned-commit --minimal` flags](../../install_executorch.py): - ```bash - ./install_executorch.sh --use-pt-pinned-commit --minimal - ``` + For Intel-based macOS systems, use the [`--use-pt-pinned-commit --minimal` flags](../../install_executorch.py): + ```bash + ./install_executorch.sh --use-pt-pinned-commit --minimal + ``` Not all backends are built into the pip wheel by default. You can link these missing/experimental backends by turning on the corresponding cmake flag. For example, to include the MPS backend: