Last updated 18 May 2017
Table of Contents
The Heroku Command Line Interface (CLI), formerly known as the Heroku Toolbelt, is a tool for creating and managing Heroku apps from the command line / shell of various operating systems.
Download and install
To install the Heroku CLI with homebrew:
$ brew install heroku
Compatible with 10.7+
Download and run the MacOS installer.
Compatible with 10.7+
Windows Bash and Ubuntu/Debian
Run the following to add our apt repository and install the CLI:
For Windows Bash you must install the Windows Subsystem for Bash and execute these commands through bash, not cmd.exe or PowerShell.
$ sudo apt-get install software-properties-common # debian only $ sudo add-apt-repository "deb https://cli-assets.heroku.com/branches/stable/apt ./" $ curl -L https://cli-assets.heroku.com/apt/release.key | sudo apt-key add - $ sudo apt-get update $ sudo apt-get install heroku
Download the tarball and extract it so that you can access the binary from your PATH. For example:
# replace REPLACE_ME_OS/REPLACE_ME_ARCH with values as noted below $ wget https://cli-assets.heroku.com/branches/stable/heroku-REPLACE_ME_OS-REPLACE_ME_ARCH.tar.gz -O heroku.tar.gz $ mkdir -p /usr/local/lib $ tar -xvzf heroku.tar.gz -C /usr/local/lib $ /usr/local/lib/heroku/install
Where REPLACE_ME_OS is one of “linux”, “darwin”, “windows”, “freebsd”, “openbsd” and REPLACE_ME_ARCH is one of “amd64”, “386” or “arm”
Verify your installation
To verify your CLI installation use the
heroku --version command.
$ heroku --version heroku-cli/6.6.1-010a227 (darwin-x64) node-v7.10.0
You should see
heroku-cli/x.y.z in the output. If you don’t, but have installed the Heroku CLI, it’s possible you have an old heroku gem on your system - uninstall the gem.
You will be asked to enter your Heroku credentials the first time you run a command; after the first time, your email address and an API token will be saved to
~/.netrc for future use. For more information, see Heroku CLI Authentication
It’s generally a good idea to login and add your public key immediately after installing the Heroku CLI so that you can use git to push or clone Heroku app repositories:
$ heroku login Enter your Heroku credentials. Email: email@example.com Password (typing will be hidden): Authentication successful.
You’re now ready to create your first Heroku app:
$ cd ~/myapp $ heroku create Creating app... done, ⬢ sleepy-meadow-81798 https://sleepy-meadow-81798.herokuapp.com/ | https://git.heroku.com/sleepy-meadow-81798.git
Check out our Getting Started for a comprehensive introduction to deploying your first app.
Staying up to date
The Heroku CLI will automatically keep itself up to date.
Autoupdate was added to the Heroku CLI in version 2.32.0. If you have an older version, please reinstall the Heroku CLI.
How it works
When you run a
heroku command, a background process will be spawned that checks a URL for the latest available version of the CLI. If a new version is found, it will be downloaded and stored in
~/.local/share/heroku/cli. This background check will happen at most once every 4 hours.
heroku binary will check for updated clients in
~/.local/share/heroku/cli before loading the system-installed version.
If you are experiencing issues with logging in, try moving your
.netrc file. This is where the CLI stores credentials:
$ mv ~/.netrc ~/.netrc.backup $ heroku login
On Windows the file is named
Uninstalling the Heroku CLI
Note that these will also delete all plugins.
On MacOS, you can uninstall the CLI by typing:
$ rm -rf /usr/local/heroku $ rm -rf ~/.local/share/heroku ~/.config/heroku ~/Library/Caches/heroku
If you installed the Heroku CLI using Homebrew, you can uninstall the CLI by typing:
$ brew uninstall heroku $ rm -rf ~/.local/share/heroku ~/.config/heroku ~/.cache/heroku
For standalone installs, you can uninstall the CLI by typing:
$ rm /usr/local/bin/heroku $ rm -rf /usr/local/lib/heroku /usr/local/heroku $ rm -rf ~/.local/share/heroku ~/.config/heroku ~/.cache/heroku ~/.heroku
Debian and Ubuntu installs
For Debian/Ubuntu, you can uninstall the CLI by typing:
$ sudo apt-get remove heroku-toolbelt $ sudo rm /etc/apt/sources.list.d/heroku.list
If you have
$XDG_CACHE_HOME it will use those variables instead of
You can remove the release key by running these commands:
$ sudo apt-key list $ sudo apt-key del KEYFROMABOVE
On Windows, to uninstall the Heroku CLI:
- Click Start > Control Panel > Programs > Programs and Features.
- Select Heroku CLI, and then click Uninstall. (Note that the uninstaller is unsigned)
You should also delete the
.config/heroku directory inside your home directory.
If this is unsuccessful, manually delete
%LOCALAPPDATA%\heroku along with the directory in Program Files.
Uninstalling the legacy heroku gem
To find out where the executable is located, run
$ which heroku /usr/local/heroku/bin/heroku
The path to the
heroku command should not be a Ruby gem directory.
If it is, uninstall it and any other heroku gems:
$ gem uninstall heroku --all
Legacy Ruby CLI
If for any reason the new CLI does not work right, or you need to use legacy Ruby-based plugins, use one of these installers: