This topic describes how to install, configure, and use the Oracle Cloud Infrastructure Python SDK.
The Python SDK requires:
- Python version 2.7.5 or 3.5 or later
- OpenSSL version 1.0.1 or later. The Python SDK uses the Cryptography.io library which requires OpenSSL. For details on all Cryptography.io prerequisites, see Cryptography.io Installation.
In addition, all Oracle Cloud Infrastructure SDKs require:
- An Oracle Cloud Infrastructure account
- A user created in that account, in a group with a policy that grants the desired permissions. This can be a user for yourself, or another person/system that needs to call the API. For an example of how to set up a new user, group, compartment, and policy, see Adding Users in the Getting Started Guide. For a list of other typical Oracle Cloud Infrastructure policies, see Common Policies in the User Guide.
- A keypair used for signing API requests, with the public key uploaded to Oracle. Only the user calling the API should be in possession of the private key. (For more information, see Configuring the SDK.)
Downloading and Installing the SDK¶
You can install the Python SDK through the Python Package Index (PyPI), or alternatively through GitHub.
Set up a virtual environment¶
Oracle recommends that you run the SDK in a virtual environment with virtualenv. This allows you to isolate the dependencies for the SDK and avoids any potential conflicts with other Python packages which may already be installed (e.g. in your system-wide Python).
With Linux, virtualenv is usually in a separate package from the main Python package.
If you need to install virtualenv, use
pip install virtualenv.
To create and activate a virtual environment:
virtualenv <environment name> source <environment name>/bin/activate
virtualenv oci_sdk_env source oci_sdk_env/bin/activate
To install from GitHub:
Download the SDK from GitHub. The download is a zip containing a whl file and documentation.
Extract the files from the zip.
Use the following command to install the SDK:
pip install oci-*-py2.py3-none-any.whl
If you're unable to install the whl file, make sure pip is up to date. Use
pip install -U pipand then try to install the whl file again.
Configuring the SDK¶
Before using the SDK, you must set up your config file with the required credentials. For instructions, see SDK and Tool Configuration in the User Guide.
Verify OpenSSL Version¶
The supported version of OpenSSL for the Python SDK is version 1.0.1 or newer. Run the following command to find out the version of OpenSSL that you have:
python -c "import ssl; print(ssl.OPENSSL_VERSION)"
If the version is lower than
1.0.1, run the following command to bypass the version issue:
pip install requests[security]==2.18.4
If you don't want to use
requests[security] you can update OpenSSL as you normally would. For example, on OS X, use Homebrew to update OpenSSL using the following commands:
brew update brew install openssl brew install python
If you need to configure your environment for FIPS-compliance, see Using FIPS-validated Libraries
You might encounter issues when installing Python or the SDK, or using the SDK itself.
Any operation resulting in a service error will cause an exception of type oci.exceptions.ServiceError to be thrown by the SDK. For information about common service errors, see API Errors.
pip 10 Installation Errors¶
If you are attempting to install the SDK in your system-wide Python using pip 10 then you may encounter conflicts with
distutils installed packages. An example error message is:
sudo pip install oci ... ... 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.
Resolve by using a virtual environment¶
Installing the SDK in a virtual environment instead of the system-wide Python. See the Downloading and Installing the SDK section for more information
Resolve by using the system-wide Python¶
If you wish to still use the system-wide Python, you can resolve this issue by downgrading the version of
pip you are using and then trying to re-install the SDK.
sudo pip install pip==9.0.3 sudo pip install oci
If you wish to stick with
pip version 10, then you will either have to install the SDK using the
pip install oci --user
Or you will have to uninstall the distutils installed packages manually. To do this, you will have to:
Make a note of what packages cannot be uninstalled. In the example error message, the package is requests
Find the install location for these packages. You can find this by looking in the directories returned by
python -m site
One of the directories should contain a sub-directory with the same name as the package (e.g. in the case of the example error message the folder should be called requests) and a
.egg-infofile which contains the package name and a version
Delete the folder and the
Try and re-install the SDK:
sudo pip install oci