.. _install:

.. raw:: html

    <script type='text/javascript'>
        var oldDocsHost = 'oracle-bare-metal-cloud-services-python-sdk';
        if (window.location.href.indexOf(oldDocsHost) != -1) {
            window.location.href = 'https://oracle-bare-metal-cloud-services-python-sdk.readthedocs.io/en/latest/deprecation-notice.html';
        }
    </script>

Installation
~~~~~~~~~~~~

This topic describes how to install, configure, and use the Oracle Cloud Infrastructure Python SDK.

===============
 Prerequisites
===============

The Python SDK requires:

* Python version 3.6, 3.7, 3.8 and 3.9
* `OpenSSL`_ version 1.0.2 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.
* Python version as mentioned in `Supported Python Versions`_.
* 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), GitHub, OCI Resource Manager or yum on Oracle Linux.

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

For example::

    virtualenv oci_sdk_env
    source oci_sdk_env/bin/activate

PyPi
-----

To install from `PyPI <https://pypi.python.org/pypi/oci>`_ use the following command::

    pip install oci

GitHub
-------

To install from GitHub:

1. Download the SDK from `GitHub <https://github.com/oracle/oci-python-sdk/releases>`_.
   The download is a zip containing a whl file and documentation.
2. Extract the files from the zip.
3. Use the following command to install the SDK::

    pip install oci-*-py3-none-any.whl

  .. note::

      If you're unable to install the whl file, make sure pip is up to date.
      Use ``pip install -U pip`` and then try to install the whl file again.

Offline Installation
--------------------

To install the Python SDK in an environment which does not allow internet connection, you can use the OCI CLI offline install files to install the Python SDK in offline mode. Here are the steps:

1. Go to the `CLI releases page <https://github.com/oracle/oci-cli/releases>`_
2. To install the latest SDK version, go to the latest release. If you want to install a particular SDK version, follow the below steps:
    a. Find that version in the `SDK changelog <https://github.com/oracle/oci-python-sdk/blob/master/CHANGELOG.rst>`_.
    b. Note at the date this version was released.
    c. Check the `CLI changelog <https://github.com/oracle/oci-cli/blob/master/CHANGELOG.rst>`_ and find the CLI version released on the same date as the SDK version you want to install.
    d. Go to the `CLI releases page <https://github.com/oracle/oci-cli/releases>`_ and select that CLI version.
3. Go to the "Assets" area.
4. Download the .zip file for your Operating System.
5. Copy the .zip file to the environment in which you want to install the SDK.
6. Unzip the .zip file. This should create a new directory called "oci-cli-installation".
7. Use the following command to install the SDK::

    pip3 install oci --find-links ./oci-cli-installation/cli-deps --no-index

  .. note::

      If you have any issues executing the above steps, please see common installation issues here https://github.com/oracle/oci-cli/blob/master/COMMON_ISSUES.rst or create a Github issue and we will look into it.

Installing with Resource Manager
--------------------------------

You can use `Resource Manager <https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Concepts/resourcemanager.htm#Overview_of_Resource_Manager>`_
to `install the Oracle Cloud Development Kit on a Compute instance in your compartment <https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Tasks/devtools.htm#devtools>`_.
The Oracle Cloud Development Kit includes the SDK for Python, along with other Oracle development tools.

Installing with yum
-------------------

If you're using Oracle Linux 7, you can use yum to install the OCI SDK for Python.

The following example shows how to use yum to install the OCI SDK for Python 3.6::

    sudo yum install python36-oci-sdk.x86_64


=====================
 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.

.. _SDK and Tool Configuration: https://docs.cloud.oracle.com/Content/API/Concepts/sdkconfig.htm

Verify OpenSSL Version
----------------------

The supported version of OpenSSL for the Python SDK is version 1.0.2 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.2``, run the following command to bypass the version issue::

    pip install requests[security]==2.18.4

This command instructs the `requests <https://pypi.python.org/pypi/requests>`_
library used by the Python SDK to use the version of OpenSSL that is bundled with the `cryptography <https://pypi.python.org/pypi/cryptography>`_
library used by the SDK.

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

.. note::
    If you need to configure your environment for FIPS-compliance, see :doc:`fips-libraries`

=================
 Troubleshooting
=================

You might encounter issues when installing Python or the SDK, or using the SDK itself.

Service Errors
--------------
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 <https://docs.cloud.oracle.com/Content/API/References/apierrors.htm>`_.


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:

.. code-block:: none

    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 ``--user`` switch::

    pip install oci --user

Or you will have to uninstall the distutils installed packages manually. To do this, you will have to:

1. Make a note of what packages cannot be uninstalled. In the example error message, the package is **requests**
2. Find the install location for these packages. You can find this by looking in the directories returned by ``python -m site``
3. 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-info`` file which contains the package name and a version
4. Delete the folder and the ``.egg-info`` file
5. Try and re-install the SDK::

    sudo pip install oci

SSL/TLS or Certificate Issues
-----------------------------

When trying to use the SDK, if you get an exception related to SSL/TLS or certificates/certificate validation, see the command for installing requests[security] in `Verify OpenSSL Version`_.


.. _Adding Users: https://docs.cloud.oracle.com/Content/GSG/Tasks/addingusers.htm
.. _Common Policies: https://docs.cloud.oracle.com/Content/Identity/Concepts/commonpolicies.htm
.. _Cryptography.io: https://cryptography.io/en/latest/
.. _Cryptography.io Installation: https://cryptography.io/en/latest/installation/
.. _TLS 1.2: https://docs.cloud.oracle.com/Content/API/Concepts/sdks.htm
.. _PyPI link: https://pypi.python.org/pypi
.. _OpenSSL: https://www.openssl.org/
.. _ConfiguringSDK: Configuring the SDK
.. _OSXUsers: Verify OpenSSL Version
.. _Supported Python Versions: https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/pythonsdk.htm#pythonsdk_topic-supported_python_versions