Installation

This page describes how to install the coremltools Python package on macOS (10.13+) and Linux.

Prerequisites

📘

For beginners

If you are using macOS, you should already be familiar with the Mac Terminal app command line to perform tasks such as installations and updates. If you are using Linux, you should already be familiar with basic Shell commands in Linux.

Before installing coremltools, you need Python and the pip installer.

The coremltools package supports Python 2 and Python 3. We recommend that you install Python 3.6 or newer. Use a Python package manager such as Conda or venv to install the newest version of Python and other dependencies. Conda is recommended because it is the most reliable way to install all required dependencies.

🚧

Python 2.7 support

Since Python 2 is no longer supported by the Python core team, use Python 3 for the best experience with coremltools. The most recent stable release of coremltools to support Python 2 is version 4.0. Newer versions of coremltools, starting from version 4.1, does not support Python 2. Please plan your migration accordingly.

Install or build coremltools

To install coremltools, use one of the following methods:

• The Conda package installer: Python is installed automatically. You can install pip after creating the Conda environment. Skip to Install with Conda.
• A virtual environment: Install pip, and then use venv, which also installs Python. Skip to Install inside a new virtual environment.
• Install Python wheel: To download and install the most recent (or any available) Python wheel (.whl file) for coremltools, see Install from source.
• Build from source: To build the most recent (or any available) version of coremltools, see Build from source.

To install third-party frameworks, libraries, or other software, see Install third-party packages.

Install with Conda

Follow these steps:

1. Use the appropriate Miniconda installer for your operating system.

2. Create a Conda environment for coremltools using the following command:

Shell

conda create --name coremltools-env

3. Activate your virtual environment using the following command:

Shell

conda activate coremltools-env

4. Install pip for this environment using the following command:

Shell

conda install pip

5. Use the following command to install a fresh copy of coremltools:

Shell

# Install from conda-forge
conda install -c conda-forge coremltools

Install inside a new virtual environment

Follow these steps:

1. Install pip using the following command:

Shell

python -m pip install --user --upgrade pip

2. Create a virtual environment using the following command:

Shell

python -m venv coremltools-venv

3. Activate and install coremltools using the following commands:

Shell

source coremltools-venv/bin/activate
pip install --upgrade coremltools

Install third-party packages

Install the third-party source packages for your conversions (such as TensorFlow and PyTorch) using the package guides provided for them. The coremltools package does not include the third-party source packages.

Upgrade coremltools

For either Conda or virtual environments, use the following command to upgrade to the newest version:

Shell

# Upgrade
pip install --upgrade coremltools

Install from source

The continuous integration (CI) system linked to the coremltools repo builds a Python wheel from the master branch whenever a commit is merged. To get the latest updates to the code base, you can get this wheel from the CI job and install it.

To access the wheel for a particular coremltools release, follow these steps:

1. Go to the Apple coremltools repository on GitHub, scroll down to the README.md heading, and click the build passing button. The Branches tab appears.

2. Click the passed button to show the Pipeline tab.

3. Click a wheel in the Build column. For example, in the previous figure, the build_wheel_macos_py38 wheel is highlighted for clicking. After clicking a wheel, the raw job log appears, with the Download and Browse buttons in the right column.

4. Click the Download button to download the dist folder with the wheel files.

5. Install a wheel file using pip. For example, use this command to install the coremltools-4.0-cp38-none-macosx_10_12_intel.whl wheel file:

Shell

pip install coremltools-4.0-cp38-none-macosx_10_12_intel.whl

Build from source

To build coremltools and its dependent libraries from source, you need to install CMake to configure the project.

To perform the build, fork and clone the GitHub coremltools repository and run the build.sh script:

Shell

zsh -i build.sh

The script creates a new build folder with the coremltools distribution, and a dist folder with Python wheel files.

For more information about building coremltools, see Building From Source.