In this post, we walk through the steps required to access your machine's GPU within a Docker container.
Configuring the GPU on your machine can be immensely difficult. The configuration steps change based on your machine's operating system and the kind of NVIDIA GPU that your machine has. To add another layer of difficulty, when Docker starts a container - it starts from almost scratch. Certain things like the CPU drivers are pre-configured for you, but the GPU is not configured when you run a docker container. Luckily, you have found the solution explained here. It is called the NVIDIA Container Toolkit!
Potential Errors in Docker
When you attempt to run your container that needs the GPU in Docker, you might receive any of the following errors.
You may receive many other errors indicating that your Docker container cannot access the machine's GPU. In any case, if you have any errors that look like the above, you have found the right place here. The steps below will get you past them.
First, Make Sure Your Base Machine Has GPU Drivers
You must first install NVIDIA GPU drivers on your base machine before you can utilize the GPU in Docker. As previously mentioned, this can be difficult given the plethora of distribution of operating systems, NVIDIA GPUs, and NVIDIA GPU drivers. The exact commands you will run will vary based on these parameters. Here are some resources that you might find useful to configure the GPU on your base machine.
- NVIDIA's official toolkit documentation
- Installing NVIDIA drivers on Ubuntu guide
- Installing NVIDIA drivers from the command line
Once you have worked through those steps, you will know you are successful by running the nvidia-smi command and viewing an output like the following.
Now that we can assure we have successfully assure that the NVIDIA GPU drivers are installed on the base machine, we can move one layer deeper to the Docker container.
Next, Exposing the GPU Drivers to Docker
In order to get Docker to recognize the GPU, we need to make it aware of the GPU drivers. We do this in the image creation process. Docker image creation is a series of commands that configure the environment that our Docker container will be running in.
The Brute Force Approach - The brute force approach is to include the same commands that you used to configure the GPU on your base machine. When docker builds the image, these commands will run and install the GPU drivers on your image and all should be well. The brute force approach will look something like this in your Dockerfile.
The Downsides of the Brute Force Approach - First of all, every time you rebuild the docker image you will have to reinstall the image, slowing down development. Second, if you decide to lift the docker image off of the current machine and onto a new one that has a different GPU, operating system, or you would like new drivers - you will have to re-code this step every time for each machine. This kind of defeats the purpose of build a Docker image. Third, you might not remember the commands to install the drivers on your local machine, and there you are back at configuring the GPU again inside of Docker.
The Best Approach - The best approach is to use the NVIDIA Container Toolkit. The NVIDIA Container Toolkit is a docker image that provides support to automatically recognize GPU drivers on your base machine and pass those same drivers to your Docker container when it runs. So if you are able to run nvidia-smi, on your base machine you will also be able to run it in your Docker container (and all of your programs will be able to reference the GPU). In order to use the NVIDIA Container Toolkit, you simply pull the NVIDIA Container Toolkit image at the top of your Dockerfile like so - nano Dockerfile:
In that Dockerfile we have imported the NVIDIA Container Toolkit image for 10.2 drivers and then we have specified a command to run when we run the container to check for the drivers. Now we build the image like so with docker build . -t nvidia-test:
Now we run the container from the image by using the command docker run --gpus all nvidia-test. Keep in mind, we need the --gpus all or else the GPU will not be exposed to the running container.
From this base state, you can develop your app accordingly. In my case, I use the NVIDIA Container Toolkit to power experimental deep learning frameworks. The layout of a fully built Dockerfile might look something like the following (where /app/ contains all of the python files):
The above Docker container trains and evaluates a deep learning model based on specifications using the base machines GPU. Pretty cool!
What if I need a different base image in my Dockerfile - Let's say you have been relying on a different base image in your Dockerfile. Then, you should consider using the NVIDIA Container Toolkit alongside the base image that you currently have by using Docker multi-stage builds.
The Power of the NVIDIA Container Toolkit - Now that you have you written your image to pass through the base machine's GPU drivers, you will be able to lift the image off the current machine and deploy it to containers running on any instance that you desire.
Don't want to bother with all this?
Congratulations! Now you know how to expose GPU Drivers to your running Docker container using the NVIDIA Container Toolkit.
Want to use your new Docker capabilities to do something awesome? You might enjoy our other posts on training a state of the art object detection model, training a state of the art image classification model, or simply by looking into some free computer vision data!