Last updated 21 September 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.
It is built with node.js and the code is open sourced. It does not require node.js or other dependencies to run. In all but the ubuntu/debian and npm install methods it will contain its own node.js binary that will not conflict or be available to other applications. It will automatically update itself, the internal version of node, and any installed CLI plugins.
Download and install
To install the Heroku CLI with homebrew:
$ brew install heroku/brew/heroku
If you get legacy warnings even though you installed the latest homebrew version of heroku, this is happening because the binary
heroku command in your
PATH environment variable is not pointing to the version that brew installed.
which heroku to see what binary
heroku is pointing to. If it is not
/usr/local/bin/heroku, you need to either delete the binary it is pointing to, or make
/usr/local/bin/ higher up in your
PATH environment variable by modifying your
~/.bashrc file or equivalent.
brew link --overwrite heroku to make sure that
/usr/local/bin/heroku is pointing to the new CLI. If you continue to have trouble, run
brew doctor which should point out any issues with your system.
Compatible with 10.7+
Download and run the MacOS installer.
Compatible with 10.7+
This version does not autoupdate. You’ll have to manually update the cli with apt-get. Use the standalone install for an autoupdating version of the CLI.
Run the following to add our apt repository and install the CLI:
$ wget -qO- https://cli-assets.heroku.com/install-ubuntu.sh | sh
The script is easily typed in manually if you prefer not to pipe commands to sh.
The standalone install is a simple tarball with a binary that is useful in scripted environments or where there is restricted access (non-sudo). These are sample instructions that can be modified to fit your environment. It contains its own node.js binary and will autoupdate like the above install methods.
Download the tarball and extract it so that you can access the binary from your PATH. For example:
Don’t just copy and paste! Some modification is required. (see below)
# replace REPLACE_ME_OS/REPLACE_ME_ARCH with values as noted below $ wget https://cli-assets.heroku.com/heroku-cli/channels/stable/heroku-cli-REPLACEME_OS-REPLACE_ME_ARCH.tar.gz -O heroku.tar.gz $ tar -xvzf heroku.tar.gz $ mkdir -p /usr/local/lib /usr/local/bin $ mv heroku-cli-v6.x.x-darwin-64 /usr/local/lib/heroku $ ln -s /usr/local/lib/heroku/bin/heroku /usr/local/bin/heroku
Where REPLACE_ME_OS is one of “linux”, “darwin”, “windows” and REPLACE_ME_ARCH is one of “x64”, “x86”, or “arm” You also must replace “6.x.x” with the actual version.
The CLI is built with node.js and is installable via npm. This is a manual install method that can be used in environments where autoupdating is not ideal or where we do not offer a prebuilt node.js binary.
It’s strongly recommended to use one of the other installation methods if possible This installation method will not autoupdate and requires you to use the system node which may be older than the node we develop for. We tend to use very current releases of node and do not back-support older versions. If you use any of the other methods of install, it will include node and won’t conflict with any node on the system.
This installation method is required for users on ARM, BSD, and Arch Linux. You must have node and npm installed already.
$ npm install -g heroku-cli
Verify your installation
To verify your CLI installation use the
heroku --version command.
$ heroku --version heroku-cli/6.0.0-010a227 (darwin-x64) node-v8.0.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 and its plugins (except linked plugins) up to date unless you’re using the npm install method or debian/ubuntu package.
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/client. This background check will happen at most once every 4 hours.
heroku binary will check for updated clients in
~/.local/share/heroku/client before loading the system-installed version.
If you’re having trouble using the CLI, here are some helpful environment variables that can be set:
||Show debugging information mostly related to Heroku API interactions|
||Same as above but adds HTTP headers (only for “v6” commands)|
||Very verbose debugging information|
If you’re having issues you can also read the error logfile stored at the following locations:
If you’re having issues, first ensure you’re on the latest version of the CLI. If you’re not, try updating with
Not all methods of installation are updatable with
heroku update. Apt users will have to use
sudo apt-get update && sudo apt-get upgrade heroku.
npm/yarn users will have to update with
npm upgrade -g heroku-cli or
yarn global upgrade heroku-cli.
If updating does not update the CLI, try uninstalling with the uninstall instructions below. Ensure you don’t have Toolbelt installed or the old Heroku gem. Use
which heroku or
where heroku (on Windows) to find what
heroku points to. You may need to modify your PATH to include
/usr/local/bin/heroku (for most installations).
If you continue to have problems and the CLI is up to date, or if updating fails for other reasons, you can reset the CLI by deleting its user directories. They will all be replaced automatically and you will not be logged out, but you will lose any installed plugins.
heroku plugins to list out any installed plugins so you can reinstall them.
Then delete the following directories:
~/Library/Caches/herokuon MacOS, or
~/.cache/herokuon Linux/Other (or
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 ~/Library/Caches/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 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)
The uninstaller has been updated over the years and does not get updated through autoupdates. If it has been a while since you first installed the CLI and you’re attempting to reinstall it to fix an issue, you may need to install the CLI to receive a new uninstaller and uninstall it again for it to fully uninstall everything.
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: