Install CumulusCI

Learning Objectives

  • Install CumulusCI on macOS or Windows.
  • Verify that CumulusCI is installed.

If you already have CumulusCI installed, type the cci version command to make sure you’re using the latest version before continuing with this unit. If you’re told there is a newer version, run the command noted in the version information outlined in the Terminal.

Tasha and her team are ready to take the next step of installing CumulusCI. If you're following along, note that the time estimate for this unit is just an estimate. Your own installation might take longer, depending on your system configuration and network speed.

Mac Users

On Mac, the easiest way to install CumulusCI is to install Homebrew.

  1. Open VS Code and go to the Terminal panel.
  2. Copy the following command and enter it in the Terminal panel: /bin/bash -c "$(curl -fsSL"
  3. If you are prompted for a password, enter your computer's password to allow your computer to install Homebrew. You may not see any characters in your Terminal as you type your password.

After you enter your password and press Return, the Terminal window shows the steps being completed to install Homebrew (many of the activities will be related to installing Python).

  1. When the installation is done, the Terminal window will show you a prompt (perhaps a $ symbol) indicating you can enter another command.
  2. Install Python with the following command: brew install python3
  3. Install CumulusCI with the following command: brew tap SFDO-Tooling/homebrew-sfdo && brew install cumulusci

It should take around four minutes to install. When it's done, you'll see your command prompt reappear. You’re done! Skip to the Verify CumulusCI Installation section of this unit.

Windows Users

Install Python 3

  1. Go to the Python 3.9 downloads page.
  2. In the Files section, select a suitable installer for your computer. If you don't know which release is suitable, choose “Windows x86-64 executable installer”.
  3. After the installer is downloaded, open the installation wizard.
  4. You must add Python to PATH. The checkbox for this will read something like “Add Python [version number] to PATH”.
  5. Use the Install Now option; you do not need to customize the installation.

Install pipx

  1. Open VS Code and go to the Terminal in the Panel. If you already have VS Code open, close it and reopen it.
  2. Enter this command: python -m pip install --user pipx

Some warnings about PATH during the installation of pipx are normal. We’ll address the causes of those warnings in a moment.

Modify PATH in Environment Variables

To ensure that all of your Terminal environments know where to find Python and the Python scripts that you install (including CumulusCI), edit your computer’s environment variables. Editing these settings requires non-restricted access to your machine (administrator rights).

  1. Search your computer for “edit environment variables”. It’s typically in Advanced System Settings in Control Panel.
  2. Click Environment Variables.
  3. Select the PATH user environment variable and click Edit.
  4. Click New and add these values:
    1. %USERPROFILE%\AppData\Roaming\Python\Python39\Scripts 
    2. %USERPROFILE%\.local\bin

System properties screen
Advanced System Settings screen

Verify pipx is Installed

  1. Close VS Code and reopen it.
  2. Open a new Terminal (Terminal→New Terminal).
  3. Enter the following command to verify that pipx is available: pipx --version

You should see a version number such as: If you get an error instead, such as 'pipx' is not recognized as an internal or external command, operable program or batch file, check that your environment variables have been updated and that you’ve opened a new terminal.

Install CumulusCI

Still in the VS Code Terminal, enter this command: pipx install cumulusci

The CumulusCI installation will begin and might take a few moments. You’ll see a confirmation message when the installation is complete.

Verify CumulusCI Installation (Mac or Windows)

Make sure the CumulusCI command is available by entering this command: cci

On first use, Mac users may see a popup asking for permission to store a password in your keychain. This request is expected, so enter your computer’s password and click Always Allow. You should see output like the following:

Usage: cci [OPTIONS] COMMAND [ARGS]...
 --help  Show this message and exit.
 flow     Commands for finding and running flows for a project
 org      Commands for connecting and interacting with Salesforce orgs
 project  Commands for interacting with project repository configurations
 service  Commands for connecting services to the keychain
 shell    Drop into a Python shell
 task     Commands for finding and running tasks for a project
 version  Print the current version of CumulusCI

If you see an error message or something different, try installing CumulusCI again.


Keep learning for
Sign up for an account to continue.
What’s in it for you?
  • 1 in 4 land a new job
  • 50% receive a promotion or raise
  • 80% learn new technologies that boost their resume
  • 66% say it increases productivity
Source: Trailblazer Community Impact Survey 2019