Installing the CLI

This topic describes the installation options and the steps to install the CLI and required software.

Requirements and Installation Options

Before you install the CLI, review the following requirements.

Requirements

To install and use the CLI, you must have:

  • An Oracle Cloud Infrastructure account
  • A user created in that account, in a group with a policy that grants the desired permissions. This account user can be you, another person, or a system that calls the API. For an example of how to set up a new user, group, compartment, and policy, see Adding Users. For a list of other typical Oracle Cloud Infrastructure policies, see Common Policies.
  • A keypair used for signing API requests, with the public key uploaded to Oracle. Only the user calling the API should possess the private key. See Configuring the CLI.
  • Python version 2.7.5 or 3.5 or later, running on Mac, Windows, or Linux. Note that if you use the CLI Installer and do not have Python on your machine, the Installer offers to automatically install Python for you. If you already have Python installed on your machine, you can use the python --version command to find out which version is installed.

Installation Options

There are two ways to install the CLI and you can use the one that is best suited for your environment. Use either of the following options:

  • Automatically installing the CLI and dependencies with the CLI installer
  • Manually installing the CLI and dependencies within a virtual environment

Using the CLI Installer

The installer uses a script to install the CLI and programs that are required. You can use the installer to eliminate most of the manual steps to install the CLI. The installer script:

  • Installs Python

    • During installation, you are prompted to provide a location for installing the binaries and executables. If Python is not installed on your computer, or the installed version of Python is incompatible with the CLI, you are prompted to install Python.
    • The installer doesn't try to install Python on a MacOS computer. However, the script notifies you if the version of Python on the computer is too old or incompatible.
  • Installs virtualenv and creates a virtual environment
  • Installs the latest version of the CLI

    • The installer overwrites an existing installation if you chose to do so. Respond with Y when prompted to upgrade the CLI to the newest version.
    • During the installation, you are asked if you want to update your PATH. Updating the PATH adds the CLI executable ("oci.exe") to your PATH. Adding oci.exe to the PATH lets you invoke the CLI without providing the full path to the executable. If you want to update your PATH, respond with Y when prompted. You are notified when to close and restart the terminal session.

Manually Installing the CLI in a Virtual Environment

This section describes how to install the CLI by following the sequence of steps that are provided.

Installing Python

Python installation instructions vary for each operating system.

Installing and Configuring virtualenv

Run the CLI in a virtual environment using the following installation sequence:

  • Install virtualenv and then create the environment
  • Activate the virtualenv environment
  • Run pip install oci-cli

The virtualenv Software

virtualenv is a virtual environment builder that lets you create isolated Python environments. First, you have to download and install virtualenv and then install the CLI in the virtual environment. (For Linux users, virtualenv is usually in a separate package from the main Python package.)

Download the software and documentation from:

Installing and Configuring virtualenv

After Python is installed, install and configure virtualenv.

Installing the Command Line Interface

Use the following steps to install the CLI in a virtual environment.

You can download the CLI from GitHub or install the package from Python Package Index (PyPI).

To install using the GitHub download:

  • To download the file, click oci-cli.zip.
  • Unzip the file and then run the following command.

    pip install oci_cli-*-py2.py3-none-any.whl

To install using PyPI, run the following command.

pip install oci-cli

Installing Without a Virtual Environment

In cases where you are trying to install the CLI in your system-wide Python using the latest pip version, you might encounter conflicts with some distutils installed packages. Following is an example error message when this occurs:

sudo pip install oci-cli
...
...
Cannot uninstall 'requests'. It is a distutils installed project and thus we cannot accurately determine which files belong to it which would lead to only a partial uninstall.

We do not recommend installing the CLI in your system-wide Python and suggest that instead you install the CLI using the installer or virtual environment as discussed above. Another option is to install the CLI for the user using the following command, although this approach is not supported:

pip install --user oci-cli

Starting the CLI in a Virtual Environment

Your operating system determines which commands are used to start a CLI session in a virtual environment.