ModusToolbox Installation Guide

This guide provides instructions for installing the ModusToolbox software version 2.1 – a set of tools that enable you to integrate Cypress devices into your existing development methodology. Refer to earlier revisions of this guide for instructions to install previous ModusToolbox software versions.

System Requirements

The ModusToolbox software consumes approximately 2 GB of disk space. Like most modern software, it requires both free disk space and memory to run effectively. Cypress recommends a system configuration with a PassMark CPU score > 2000 (, at least 25 GB of free disk space, and 8 GB of RAM. The product will operate with fewer resources; however, performance may be degraded.

ModusToolbox software is not supported on 32-bit operating systems. It has been tested on the following:

Windows 7 64-bit / Windows 10 64-bit macOS 10.x

Ubuntu Linux 18.04 LTS (Note ModusToolbox software requires libssl1.0.0, which is not provided in Ubuntu 20.04 for example.)


For Linux and macOS, ModusToolbox software requires the following Unix packages (with minimum versions) to work properly:

  • make (v3.81)

  • mktemp (v8.25)

  • perl (v5.18.2)

  • cmp (v2.8.1)

  • git (2.17.0)

Some versions of Ubuntu Linux do not include ‘make’ by default. Use the following command to install it:

sudo apt-get install make

Installing with Previous Versions

ModusToolbox version 2.1 installs alongside previous versions of the software (version 1.0, 1.1, and 2.0); therefore, all versions can be used independently. However, refer to the “Production Versioning” section in the ModusToolbox User Guide to understand how versions interact with each other.

If you installed a version 2.1 Beta release, you need to uninstall it before installing this production release.

  • Windows: The current release installer will prompt you to uninstall a previous version 2.1 installation. You can also use the Windows Control Panel.

  • Linux: Go to the directory where you extracted the tar.gz installer. Delete only the tools_2.1 and ide_2.1 directories from the “ModusToolbox” directory.

  • macOS: The current release installer contains a check box to uninstall a previous version 2.1 installation.


If you plan to use the Eclipse IDE included with the installation, be aware that uninstalling the ModusToolbox software does not remove any Eclipse IDE workspaces you may have previously created. You should manually delete these workspaces or move them to another location. See also Step 3: Run the Eclipse IDE for more details about workspaces.

Step 1: Download the Software

Go to the Cypress ModusToolbox website ( and download the appropriate software for your platform:

  • Windows: ModusToolbox_2.1.0.<build>-windows-install.exe

  • Linux: ModusToolbox_2.1.0.<build>-linux-install.tar.gz

  • macOS: ModusToolbox_2.1.0.<build>-macos-install.pkg


If you plan to use the SEGGER J-link debugger, you must download and install the appropriate software pack for your OS. It is not included with the ModusToolbox software. Use version 6.35 or later. For Linux, if you install this using the tar.gz file, make sure you install J-Link in a common location. Otherwise, you must configure the Eclipse IDE to specify the location, as follows:

Window > Preferences > MCU > Global SEGGER J-Link Path

  • Executable: JLinkGDBServerCLExe

  • Folder: <J-Link_extracted_location>

Step 2: Install ModusToolbox Software


Do not use spaces in the installation directory name. Various tools, such as Make, do not support spaces. Also, do not use common illegal characters, such as:

* . “ ‘ / \ [ ] : ; | = ,


If your user home directory contains spaces, see Installing with Spaces in User Home Directory.


If you install ModusToolbox in a non-default location, you will need to set the CY_TOOLS_PATHS environment variable for your system to point to the <install_path>/ModusToolbox/tools_2.1 folder, or set that variable in each Makefile. You must use forward slashes in the variable’s path, even in Windows. Refer to the “Production Versioning” section in the ModusToolbox User Guide.


Run the ModusToolbox_2.1.0.<build>-windows-install.exe installer program. By default, it is installed here:



If you have not installed ModusToolbox software previously, you may be prompted to restart your computer due to installation of Microsoft Visual C++ redistributable files.


Extract the ModusToolbox_2.1.0.<build>-linux-install.tar.gz file to your <user_home> directory. The extraction process will create a “ModusToolbox” directory there, if there is not one there already.

After extracting, you must run the following scripts before running ModusToolbox software on your machine:

  • OpenOCD: <user_home>/ModusToolbox/tools_2.1/openocd/udev_rules/

  • WICED Bluetooth Boards: <user_home>/ModusToolbox/tools_2.1/driver_media/

  • Firmware Loader: <user_home>/ModusToolbox/tools_2.1/fw-loader/udev_rules/

  • Post-Install Script: <user_home>/ModusToolbox/tools_2.1/modus-shell/postinstall

For the ModusToolbox software to work correctly on Linux, you must install an additional “libusb-0.1-4” package for the Ubuntu 18.xx OS. To do that, run the following command in the Terminal window:

$ sudo apt-get install libusb-0.1-4


Double-click the downloaded ModusToolbox_2.1.0.<build>-osx-install.pkg file and follow the wizard.


On the Catalina version of macOS, you may see a dialog similar to the following:


If this happens, click OK to close the dialog. Then, right-click on the pkg file and select Open. When this dialog displays again, it will include an Open option.

The ModusToolbox software will be installed under the Applications folder in the volume you select in the wizard.


The ModusToolbox package installer installs the WICED USB driver for use with future versions of ModusToolbox. It may pop up a “System Extension Blocked” dialog. In this case, go to Security Preference and click Allow for the driver to be installed.

In order for ModusToolbox to work correctly on macOS, you must install an additional Xcode package from the Mac App Store if you don’t already have it installed. You can also install it using the following command in a terminal window:

xcode-select –-install

Step 3: Run the Eclipse IDE

The ModusToolbox software includes an optional Eclipse IDE. To run the IDE:

  • Windows: Navigate to <user_home>/ModusToolbox/ide_2.1/eclipse and run ModusToolbox.exe.


    You may be asked to grant access by the Firewall manager.

  • Linux: Navigate to <user_home>/ModusToolbox/ide_2.1/eclipse and run ModusToolbox.

  • macOS: Navigate to the directory where you moved the file (for example, /Applications/ModusToolbox/ide_2.1) and run

When the Eclipse IDE runs for the first time, a dialog opens to specify the Workspace location. The default location for the workspace is: <user_home>/mtw.


Be aware that the default Eclipse IDE workspace location (<user_home>/mtw) is the same for all versions of ModusToolbox software. If you plan to use more than one version, you must specify different workspace names for each one.


Enter the workspace location and name and click Launch to open the IDE.


If you change the workspace location or name, do not use spaces or illegal characters anywhere in the path.

After the IDE opens for the first time, the Cypress End User License Agreement (EULA) displays.


Read the EULA and click Accept to proceed. If you click Decline, the IDE will close.

Next Steps

Refer to the ModusToolbox User Guide for a description of the software and instructions to get started.

If you plan to use the Eclipse IDE included with the ModusToolbox software:

These documents are also available from the Eclipse IDE Help menu.

Installing with Spaces in User Home Directory

The ModusToolbox installer tries to install in your user home directory by default. However, it prevents you from installing into a directory that contains spaces.


If possible, create a new user account and user home directory that doesn’t contain spaces. If you cannot create a new user home directory without spaces, then you must perform some extra manual installation steps.


Even though this process is shown for Windows, these steps apply in general to macOS and Linux as well.

Step 1: Install at a custom path.

  1. Select an alternate installation path that does not include spaces. For example:


    Any path without spaces will work.

  2. After installation is complete, create a directory to store your workspaces. For example:


    You can choose any path as long as it doesn’t contain spaces.

  3. Also, create a hidden “dot” directory named “.modustoolbox” to store the cache, offline content, and manifest.loc file discussed later in this section. For example:


Step 2: Create a system variable to specify the path to Tools.

Because you are installing ModusToolbox into a non-default location, you need to specify the path to your “tools” directory using a System Variable. Open the Environment Variables dialog, and create a new System Variable. For example:

CY_TOOLS_PATHS = C:/Cypress/ModusToolbox/tools_2.1/



Use a Windows-style path (not Cygwin-style, like /cygdrive/c/). Also, use forward slashes.

Step 3: Create a system variable to specify the path to cache.

The ModusToolbox make system clones all the repos needed for your project, directly into your project. So the resulting project is self-contained. It uses cache to speed up the clone operations. Normally, the make system would create and use cache directory at:


However, you need to fix this for the new install location for ModusToolbox by changing the location where the make system keeps the cache. Open the Environment Variables dialog, and create a new System Variable. For example:

CY_GETLIBS_CACHE_PATH = C:/Cypress/.modustoolbox/cache/



Use a Windows-style path (not Cygwin-style, like /cygdrive/c/). Also, use forward slashes.

Alternately, you can disable the caching. The downside is that this will slow down the clone operation and overall project creation, as well as the library update experience. To disable the cache, create a User Variable:


Step 4: Specify the custom path to use for Offline Content and manifest.loc.

Although you may not use these features, dependencies require that you set them up while installing the software.

Offline Content Path

Specify the non-default location to the “offline” directory with a System Variable. For example:

CY_GETLIBS_OFFLINE_PATH = C:/Cypress/.modustoolbox/offline/


Likewise, create a System Variable to specify the non-default location of the manifest.loc file. For example:

CyManifestLocOverride = C:/Cypress/.modustoolbox/manifest.loc

Step 5: Configure Eclipse Workspace

If using the Eclipse IDE, you must specify a path to the workspace that does not include spaces. For example: