diff --git a/README.md b/README.md index 22a6290e47..8003b25b17 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 db1c055dc9..a6e515c5af 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 b7a97190b4..be15e7d6ea 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 76237971e2..04896cec04 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, Torchvision, and Torchaudio 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 + ``` Use the [`--pybind` flag](https://github.com/pytorch/executorch/blob/main/install_executorch.sh#L26-L29) to install with pybindings and dependencies for other backends. ```bash diff --git a/docs/source/using-executorch-ios.md b/docs/source/using-executorch-ios.md index 764e8401fc..c749a9e1d7 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 @@ -118,6 +118,13 @@ python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip ./backends/apple/mps/install_requirements.sh ``` +- **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 + ./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: diff --git a/install_executorch.py b/install_executorch.py index 4c7b51ef23..0700e5ec49 100644 --- a/install_executorch.py +++ b/install_executorch.py @@ -196,9 +196,6 @@ def _list_pybind_defines(args) -> Tuple[bool, List[str]]: def main(args): - if not python_is_compatible(): - sys.exit(1) - parser = build_args_parser() args = parser.parse_args() diff --git a/install_requirements.py b/install_requirements.py index 4c468b979d..71fdd2411a 100644 --- a/install_requirements.py +++ b/install_requirements.py @@ -75,22 +75,43 @@ def python_is_compatible(): def install_requirements(use_pytorch_nightly): + is_intel_mac = is_intel_mac_os() + + # Skip pip install on Intel macOS if using nightly. + if use_pytorch_nightly and is_intel_mac: + 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. EXIR_REQUIREMENTS = [ # Setting use_pytorch_nightly to false to test the pinned PyTorch commit. Note # that we don't need to set any version number there because they have already # been installed on CI before this step, so pip won't reinstall them - f"torch==2.8.0.{NIGHTLY_VERSION}" if use_pytorch_nightly else "torch", - ( + f"torch==2.8.0.{NIGHTLY_VERSION}" if use_pytorch_nightly else "torch" + ] + + EXAMPLES_REQUIREMENTS = [] + + # Only pip install torchvision and torchaudio if not building PyTorch from source on Intel macOS, + # to avoid having incompatible prebuilt wheels from PyPI installed. + if not is_intel_mac: + EXIR_REQUIREMENTS.append( f"torchvision==0.22.0.{NIGHTLY_VERSION}" if use_pytorch_nightly else "torchvision" - ), # For testing. - ] + ) # For testing. - EXAMPLES_REQUIREMENTS = [ - f"torchaudio==2.6.0.{NIGHTLY_VERSION}" if use_pytorch_nightly else "torchaudio", - ] + EXAMPLES_REQUIREMENTS = [ + ( + f"torchaudio==2.6.0.{NIGHTLY_VERSION}" + if use_pytorch_nightly + else "torchaudio" + ) + ] # Assemble the list of requirements to actually install. # TODO: Add options for reducing the number of requirements. @@ -98,22 +119,25 @@ def install_requirements(use_pytorch_nightly): # Install the requirements. `--extra-index-url` tells pip to look for package # versions on the provided URL if they aren't available on the default URL. - subprocess.run( - [ - sys.executable, - "-m", - "pip", - "install", - "-r", - "requirements-examples.txt", - "-r", - "requirements-dev.txt", - *REQUIREMENTS_TO_INSTALL, - "--extra-index-url", - TORCH_NIGHTLY_URL, - ], - check=True, - ) + pip_args = [ + sys.executable, + "-m", + "pip", + "install", + "-r", + "requirements-examples.txt", + "-r", + "requirements-dev.txt", + *REQUIREMENTS_TO_INSTALL, + "--extra-index-url", + TORCH_NIGHTLY_URL, + ] + + # If pytorch is built from source add no-deps flag to stop dependencies from changing torch version + if not use_pytorch_nightly: + pip_args.append("--no-deps") + + subprocess.run(pip_args, check=True) LOCAL_REQUIREMENTS = [ "third-party/ao", # We need the latest kernels for fast iteration, so not relying on pypi. @@ -139,6 +163,17 @@ def install_requirements(use_pytorch_nightly): ) +# Prebuilt wheels for Intel 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 + return platform.system().lower() == "darwin" and platform.machine().lower() in ( + "x86", + "x86_64", + "i386", + ) + + def main(args): parser = argparse.ArgumentParser() parser.add_argument(