Install for Oracle Instant Client


This page explains the way to install ruby-oci8 for Oracle Instant Client.

Look at install-full-client for Oracle Full Client.

Look at install-binary-package for Windows unless you have a special need to compile ruby-oci8 by yourself.

Look at install-on-osx for OS X.

Install Oracle Instant Client Packages

Download Instant Client Packages

Download the following packages from Oracle Technology Network.

  • Instant Client Package - Basic or Basic Lite
  • Instant Client Package - SDK
  • Instant Client Package - SQL*Plus

Note: use 32-bit packages for 32-bit ruby even though the OS is 64-bit.

UNIX zip packages

Unzip the packages as follows:

mkdir /opt
mkdir /opt/oracle
cd /opt/oracle
unzip path/to/
unzip path/to/
unzip path/to/

If /opt/oracle/instantclient12_1/ is not found, make a symbolic link to link the library.

cd /opt/oracle/instantclient12_1
ln -s


  • use instead of on HP-UX PA-RISC.
  • skip this step for AIX.
  • run yum install libaio also on Redhat.
  • run apt-get install libaio1 also on Ubuntu.

Set the library search path, whose name depends on the OS, to point to the installed directory.

OS library search path
Solaris 32-bit ruby LD_LIBRARY_PATH_32 or LD_LIBRARY_PATH
Solaris 64-bit ruby LD_LIBRARY_PATH_64 or LD_LIBRARY_PATH

Note: Look at install-on-osx for OS X.

For example:

$ LD_LIBRARY_PATH=/opt/oracle/instantclient_12_1

Though many instant client pages indicate that the environment varialbe ORACLE_HOME should be set, it isn't necessary unless Oracle Net configuration files such as tnsnames.ora and sqlnet.ora are in $ORACLE_HOME/network/admin/.

Linux rpm packages

Install the downloaded packages as follows:

rpm -i path/to/oracle-instantclient-basic-VERSION-ARCH.rpm
rpm -i path/to/oracle-instantclient-devel-VERSION-ARCH.rpm
rpm -i path/to/oracle-instantclient-sqlplus-VERSION-ARCH.rpm

Set LD_LIBRARY_PATH to point to the directory where is installed.

For example:

$ LD_LIBRARY_PATH=/usr/lib/oracle/12.1/client/lib


Unzip the packages and set PATH to point to the directory where OCI.DLL is installed.

If require "ruby-oci8" raises a load error such as "OCI.DLL: 126(The specified module could not be found. )", either OCI.DLL or a DLL depended by OCI.DLL could not be found in PATH.

If OCI.DLL is surely in PATH, the missing module is a Visual C++ runtime library in most cases. You need to install "Microsoft Visual C++ Redistributable Package" or copy a runtime library to the directory where ruby.exe resides.

Oracle Version Package Runtime Library
18.3 Microsoft Visual C++ 2013 Redistributable Package MSVCR120.DLL
12.2.0.x Microsoft Visual C++ 2013 Redistributable Package MSVCR120.DLL
12.1.0.x Microsoft Visual C++ 2010 Redistributable Package MSVCR100.DLL
11.2.0.x Microsoft Visual C++ 2005 SP1 Redistributable Package (x86, x64) MSVCR80.DLL(The file version must be 8.0.50727.762.)
11.1.0.x No separate redistributable package MSVCR71.DLL
10.2.0.x No separate redistributable package MSVCR71.DLL

Check the environment

Oracle installation

Run the following command and confirm it works fine. If it doesn't work well, check LD_LIBRARY_PATH or PATH.


ruby installation

Run the following command. If it ends with "can't find header files for ruby" or "ruby: no such file to load -- mkmf (LoadError)", you need to install ruby-devel(redhat) or ruby-dev(debian/ubuntu).

ruby -r mkmf -e ""

development tools

You need a C compiler and development tools such as make or nmake. Note that they must be same with ones used to compile the ruby. For example, you need Oracle Solaris Studio, not gcc, for ruby compiled by Oracle Solaris Studio.


If you get a problem in the following steps, look at platform-specific-issues and report-installation-issue.

gem package

Run the following command.

gem install ruby-oci8

If you get a problem, look at platform-specific-issues and report-installation-issue.

tar.gz package

Download the source code

Download the latest tar.gz package from download page.

Note: if you are using Windows and you have no special need to compile it by yourself, look at install-binary-packge.

Run make and install

UNIX or Windows(mingw32, cygwin)
gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
cd ruby-oci8-VERSION
make install

note: If you use 'sudo', use it only when running 'make install'. 'sudo' doesn't pass library search path to the executing command for security reasons.

gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
cd ruby-oci8-VERSION
nmake install