openvino/docs/install_guides/installing-openvino-docker-linux.md

Install Intel® Distribution of OpenVINO™ toolkit for Linux from a Docker Image

@sphinxdirective

This guide provides steps on creating a Docker image with Intel® Distribution of OpenVINO™ toolkit for Linux and using the image on different devices.

System Requirements ###################

.. tab:: Target Operating Systems with Python Versions

+----------------------------------------------+-------------------------+ | Operating System | Included Python Version | +==============================================+=========================+ | Ubuntu 18.04 long-term support (LTS), 64-bit | 3.8 | +----------------------------------------------+-------------------------+ | Ubuntu 20.04 long-term support (LTS), 64-bit | 3.8 | +----------------------------------------------+-------------------------+ | Red Hat Enterprise Linux 8, 64-bit | 3.8 | +----------------------------------------------+-------------------------+

.. tab:: Host Operating Systems

• Linux
• Windows Subsystem for Linux 2 (WSL2) on CPU or GPU
• macOS on CPU only

To launch a Linux image on WSL2 when trying to run inferences on a GPU, make sure that the following requirements are met:

• Only Windows 10 with 21H2 update or above installed and Windows 11 are supported.
• Intel GPU driver on Windows host with version 30.0.100.9684 or above need be installed. For more details, this article at intel.com <https://www.intel.com/content/www/us/en/artificial-intelligence/harness-the-power-of-intel-igpu-on-your-machine.html#articleparagraph_983312434>__ .
• From 2022.1 release, the Docker images contain preinstalled recommended version of OpenCL Runtime with WSL2 support.

Installation #############

• Use a prebuilt image:

  1. Get a prebuilt image from provided sources <getting-a-prebuilt-image-from-provided-sources>__
  2. Run the image on different devices <running-the-docker-image-on-different-devices>__
  3. Run samples in the Docker image <running-samples-in-docker-image>__

• If you want to customize your image, you can also build a Docker image manually:

  1. Prepare a Dockerfile <preparing-a-dockerfile>__
  2. Configure the Docker image <configuring-the-image-for-different-devices>__
  3. Run the image on different devices <running-the-docker-image-on-different-devices>__
  4. Run samples in the Docker image <running-samples-in-docker-image>__

Getting a Prebuilt Image from Provided Sources ++++++++++++++++++++++++++++++++++++++++++++++

You can find prebuilt images on:

• Docker Hub <https://hub.docker.com/u/openvino>__
• Red Hat Quay.io <https://quay.io/organization/openvino>__
• Red Hat Ecosystem Catalog (runtime image) <https://catalog.redhat.com/software/containers/intel/openvino-runtime/606ff4d7ecb5241699188fb3>__
• Red Hat Ecosystem Catalog (development image) <https://catalog.redhat.com/software/containers/intel/openvino-dev/613a450dc9bc35f21dc4a1f7>__
• Azure Marketplace <https://azuremarketplace.microsoft.com/en-us/marketplace/apps/intel_corporation.openvino>__

Preparing a Dockerfile ++++++++++++++++++++++

You can use the available Dockerfiles on GitHub <https://github.com/openvinotoolkit/docker_ci/tree/master/dockerfiles>__ or generate a Dockerfile with your settings via DockerHub CI Framework <https://github.com/openvinotoolkit/docker_ci>__ which can generate a Dockerfile, build, test and deploy an image with the Intel® Distribution of OpenVINO™ toolkit. You can also try our Tutorials <https://github.com/openvinotoolkit/docker_ci/tree/master/docs/tutorials>__ which demonstrate the usage of Docker containers with OpenVINO.

Configuring the Image for Different Devices +++++++++++++++++++++++++++++++++++++++++++

If you want to run inference on a CPU no extra configuration is needed. Go to Run the image on different devices <running-the-docker-image-on-different-devices>__ for the next step.

Configuring Docker Image for GPU

By default, the distributed Docker image for OpenVINO has the recommended version of Intel® Graphics Compute Runtime for oneAPI Level Zero and OpenCL Driver for the operating system installed inside. If you want to build an image with a custom version of OpenCL Runtime included, you need to modify the Dockerfile using the lines below (the 19.41.14441 version is used as an example) and build the image manually:

Ubuntu 18.04/20.04:

.. code-block:: sh

WORKDIR /tmp/opencl RUN useradd -ms /bin/bash -G video,users openvino &&
chown openvino -R /home/openvino

RUN apt-get update &&
apt-get install -y --no-install-recommends ocl-icd-libopencl1 &&
rm -rf /var/lib/apt/lists/* &&
curl -L "https://github.com/intel/compute-runtime/releases/download/19.41.14441/intel-gmmlib_19.3.2_amd64.deb" --output "intel-gmmlib_19.3.2_amd64.deb" &&
curl -L "https://github.com/intel/compute-runtime/releases/download/19.41.14441/intel-igc-core_1.0.2597_amd64.deb" --output "intel-igc-core_1.0.2597_amd64.deb" &&
curl -L "https://github.com/intel/compute-runtime/releases/download/19.41.14441/intel-igc-opencl_1.0.2597_amd64.deb" --output "intel-igc-opencl_1.0.2597_amd64.deb" &&
curl -L "https://github.com/intel/compute-runtime/releases/download/19.41.14441/intel-opencl_19.41.14441_amd64.deb" --output "intel-opencl_19.41.14441_amd64.deb" &&
curl -L "https://github.com/intel/compute-runtime/releases/download/19.41.14441/intel-ocloc_19.41.14441_amd64.deb" --output "intel-ocloc_19.04.12237_amd64.deb" &&
dpkg -i /tmp/opencl/*.deb &&
ldconfig &&
rm /tmp/opencl

RHEL 8:

.. code-block:: sh

WORKDIR /tmp/opencl RUN useradd -ms /bin/bash -G video,users openvino &&
chown openvino -R /home/openvino RUN groupmod -g 44 video

RUN yum update -y && yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm &&
yum update -y && yum install -y ocl-icd ocl-icd-devel &&
yum clean all && rm -rf /var/cache/yum &&
curl -L https://sourceforge.net/projects/intel-compute-runtime/files/19.41.14441/centos-7/intel-gmmlib-19.3.2-1.el7.x86_64.rpm/download -o intel-gmmlib-19.3.2-1.el7.x86_64.rpm &&
curl -L https://sourceforge.net/projects/intel-compute-runtime/files/19.41.14441/centos-7/intel-gmmlib-devel-19.3.2-1.el7.x86_64.rpm/download -o intel-gmmlib-devel-19.3.2-1.el7.x86_64.rpm &&
curl -L https://sourceforge.net/projects/intel-compute-runtime/files/19.41.14441/centos-7/intel-igc-core-1.0.2597-1.el7.x86_64.rpm/download -o intel-igc-core-1.0.2597-1.el7.x86_64.rpm &&
curl -L https://sourceforge.net/projects/intel-compute-runtime/files/19.41.14441/centos-7/intel-igc-opencl-1.0.2597-1.el7.x86_64.rpm/download -o intel-igc-opencl-1.0.2597-1.el7.x86_64.rpm &&
curl -L https://sourceforge.net/projects/intel-compute-runtime/files/19.41.14441/centos-7/intel-igc-opencl-devel-1.0.2597-1.el7.x86_64.rpm/download -o intel-igc-opencl-devel-1.0.2597-1.el7.x86_64.rpm &&
curl -L https://sourceforge.net/projects/intel-compute-runtime/files/19.41.14441/centos-7/intel-opencl-19.41.14441-1.el7.x86_64.rpm/download -o intel-opencl-19.41.14441-1.el7.x86_64.rpm
rpm -ivh ${TEMP_DIR}/*.rpm &&
ldconfig &&
rm -rf ${TEMP_DIR} &&
yum remove -y epel-release

Running the Docker Image on Different Devices +++++++++++++++++++++++++++++++++++++++++++++

Running the Image on CPU

Run the Docker image with the following command:

.. code-block:: sh

docker run -it --rm <image_name>

Note the following:

• Kernel reports the same information for all containers as for native application, for example, CPU, memory information.
• All instructions that are available to host process available for process in container, including, for example, AVX2, AVX512. No restrictions.
• Docker does not use virtualization or emulation. The process in Docker is just a regular Linux process, but it is isolated from external world on kernel level. Performance loss is minor.

Running the Image on GPU

.. note::

Only Intel® integrated graphics are supported.

Note the following:

• GPU is not available in the container by default. You must attach it to the container.
• Kernel driver must be installed on the host.
• In the container, non-root user must be in the video and render groups. To add a user to the render group, follow the Configuration Guide for the Intel® Graphics Compute Runtime for OpenCL™ on Ubuntu 20.04 <https://github.com/openvinotoolkit/docker_ci/blob/master/configure_gpu_ubuntu20.md>__.

To make GPU available in the container, attach the GPU to the container using --device /dev/dri option and run the container:

• Ubuntu 18 or RHEL 8:

  .. code-block:: sh

  docker run -it --rm --device /dev/dri <image_name>

  .. note::

  If your host system is Ubuntu 20, follow the Configuration Guide for the Intel® Graphics Compute Runtime for OpenCL™ on Ubuntu* 20.04 <https://github.com/openvinotoolkit/docker_ci/blob/master/configure_gpu_ubuntu20.md>__.

• WSL2:

  .. code-block:: sh

  docker run -it --rm --device /dev/dxg --volume /usr/lib/wsl:/usr/lib/wsl <image_name>

  .. note::

  To launch a Linux image on WSL2, make sure that the additional System Requirements <system-requirements>__ are met.

Running Samples in Docker Image ###############################

To run the Hello Classification Sample on a specific inference device, run the following commands:

CPU:

.. code-block:: sh

docker run -it --rm <image_name> /bin/bash -c "cd ~ && omz_downloader --name googlenet-v1 --precisions FP16 && omz_converter --name googlenet-v1 --precision FP16 && curl -O https://storage.openvinotoolkit.org/data/test_data/images/car_1.bmp && python3 /opt/intel/openvino/samples/python/hello_classification/hello_classification.py public/googlenet-v1/FP16/googlenet-v1.xml car_1.bmp CPU"

GPU:

.. code-block:: sh

docker run -itu root:root --rm --device /dev/dri:/dev/dri <image_name> /bin/bash -c "omz_downloader --name googlenet-v1 --precisions FP16 && omz_converter --name googlenet-v1 --precision FP16 && curl -O https://storage.openvinotoolkit.org/data/test_data/images/car_1.bmp && python3 samples/python/hello_classification/hello_classification.py public/googlenet-v1/FP16/googlenet-v1.xml car_1.bmp GPU"

Additional Resources ###############################

• DockerHub CI Framework <https://github.com/openvinotoolkit/docker_ci>__ for Intel® Distribution of OpenVINO™ toolkit. The Framework can generate a Dockerfile, build, test, and deploy an image with the Intel® Distribution of OpenVINO™ toolkit. You can reuse available Dockerfiles, add your layer and customize the image of OpenVINO™ for your needs.
• Intel® Distribution of OpenVINO™ toolkit home page <https://software.intel.com/en-us/openvino-toolkit>__
• OpenVINO Installation Selector Tool <https://www.intel.com/content/www/us/en/developer/tools/openvino-toolkit/download.html>__

@endsphinxdirective