How-To Setup NVIDIA Docker and NGC Registry on your Workstation – Part 4 Accessing the NGC Registry

As promised, I am finally getting to that wonderful NVIDIA NGC registry I have been talking about. I first mentioned NGC in a post where I was running some machine learning job testing on the NVIDIA Titan V. Using the NGC docker registry for that testing was a big time saver. In that post I made a strong recommendation for using the NGC docker registry. Here’s the post, NVIDIA Titan V vs Titan Xp Preliminary Machine Learning and Simulation Tests.

The posts that provide the how-to information to get a system ready to use NGC are,

Those posts provide a lot of “How and Why” for the setup. Even thought there are three moderately long posts the actual setup is not hard and really doesn’t take that long to do. The posts were intended to give a detailed guide and convey understanding of the whole process. After you read and understand those posts you could probably do the entire setup in less than an hour including the time waiting for packages to download and install.

Lets get on to the good part …

What is the NGC registry?

The NGC registry is the main component of NGC. NGC stands for “NVIDIA GPU Cloud”. That consists of an NVIDIA maintained Docker registry and an AWS machine instance (AMI) on Amazon AWS. That AMI has a setup similar to what I have gone through in first 2 posts of this series (User-namespaces are not configured).

It’s the NGC Docker registry that contains all of the great container images and you can use those docker images on your own workstation. You don’t need to access AWS and you don’t need to have an AWS account. However, you do need to sign up for NGC in order to get a registry key to access those docker images. It’s a private registry so you need an account with NVIDIA NGC and the registry key to login to it.

What’s in the NGC Registry?

There are 4 section in the registry,

  • Deep Learning
  • HPC Apps
  • HPC Visualization
  • And a few “partner” docker images

Here are the GPU optimized application container images is in the repository as of this writing, (using labels as listed in the registry repository)



  • caffe
  • caffe2
  • cntk
  • cuda
  • digits
  • mxnet
  • pytorch
  • tensorflow
  • tensorrt
  • theano
  • torch


  • gamess
  • gromacs
  • lammps
  • namd
  • relion


  • paraview-holodeck
  • paraview-index
  • paraview-optix


  • chainer
  • h2oai-driverless
  • mapd
  • paddlepaddle

As you can see it is mostly NVIDIA GPU optimized machine learning frameworks. The HPC apps are GAMESS (Quantum Chemistry), GROMACS, LAMMPS, and NAMD (Molecular Dynamics) and RELION (Bayesian analysis for Cryo electron microscopy). There is some Paraview visualization software container images and some “Partner” images which are all machine learning and data analysis related. That is a nice list of applications!

Each of the container image pages has a thorough description of the application and full docker command-line launch instruction (but you will normally want to modify those to fit your specific needs). These instruction included suggested additional instance tuning options and links to full documentation for the applications. There are several tagged container image versions available and NVIDIA is trying to maintain a monthly update schedule. Nice!

How to create an NGC account and obtain your registry login key.

You will need to sign up for an NGC account. On the main NVIDIA GPU Cloud (NGC) page you will find some general information about NGC and button links to a sign up page. Clicking on one of those buttons will take you to a page to fill out information for your account.


The sign-up page is pretty simple,


The “NVIDIA ACCOUNT TERMS OF USE” is the same one you would have agreed to when registering as a NVIDIA developer. It is not the “Terms of Use” agreement for NGC. That comes up after you have singed-up.

After you have signed up you will receive an email with a link to the sign-in page where you will be greeted with panel asking you to set a password. After setting your password you will see the Terms-Of-Service for NGC,


I did read it! I didn’t see anything unexpected or too offensive in there but your taste may differ. You should read it. After accepting the terms of service you will be on the NGC docker registry web site.


From this page you will need to click on the “Configuration” button in the left pane to get to the page to generate your API Key.


Save that key. You could copy it to the clipboard and then past it into a file on your machine. You will need this key as your “password” to login to the NVIDIA NGC docker registry. If you do delete or misplace that key you can generate a new one, but you should take care of it, don’t expose it to the public etc.. One of the things you agree to when you click “accept” is to not share that key.

How to Access the NVIDIA NGC Docker Registry

The NGC docker registry is private. That means you have to login to it for access, which you can now do since you have an account and an API key.

Login to the NGC registry from docker before to access the container images.

The registry domain name is, a.k.a. NVIDIA Container Registry.
There are a couple of ways you can login,

docker login

that will ask for Username the user name is $oauthtoken and that’s the default so you can just hit return.

Username ($oauthtoken):
Password:  paste-you-API-key-here

You need to paste your API Key in as the password. Then you should see,

Login Succeeded

At that point you can start pulling and running containers from NGC.

… Or, create a file (or alias) to make that a single command.

To make that process a little easier you can put the following into a file, (maybe call it ngc-login)

docker login -u '$oauthtoken' --password-stdin <<< ' your API key here between the quotes '

Then to change the permisions to make it only accessible by you,

chmod 700 ngc-login

Now it you have a "bin" directory in your home directory that is on your path. You can put the file there and and then when you want to run NGC docker containers just run the command, ngc-login.

Note: if you don't have a "bin" directory in your home directory you can do mkdir $user/bin. Ubuntu 16.04 by default puts $user/bin on your PATH if the directory exists. It's a good place to put utility functions that you write for yourself.

A quick test to be sure things are working right ...

I'm going to end with a simple quick test just to be sure access to the NVIDIA NGC docker images is working correctly.

The following command will pull and start the CUDA image from the NGC registry, execute nvidia-smi in the container and then exit.

kinghorn@i9:~/projects/MC-NV-docker$ docker run --runtime=nvidia --rm nvidia-smi
Unable to find image '' locally
9.0-cudnn7-devel-ubuntu16.04: Pulling from nvidia/cuda
2256ead16a45: Pull complete
5d7350416e28: Pull complete
66628a092a2f: Pull complete
d3d0e57c2b41: Pull complete
81344d376930: Pull complete
3d354b8d8afb: Pull complete
1e0330af40d7: Pull complete
82359aa539a8: Pull complete
011cc48d11cf: Pull complete
6f7693a39b4b: Pull complete
a16559ce5616: Pull complete
9a943969c67c: Pull complete
a51841bef2a4: Pull complete
8cff1b0cdb65: Pull complete
Digest: sha256:c9694c236772856370758fed794e8ec566f8ee5610b04e8a99a85cc79281d1ef
Status: Downloaded newer image for
Fri Feb 16 22:25:15 2018       
| NVIDIA-SMI 387.34                 Driver Version: 387.34                    |
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|   0  GeForce GTX 108...  Off  | 00000000:65:00.0  On |                  N/A |
| 28%   31C    P8    11W / 250W |    536MiB / 11170MiB |      1%      Default |

| Processes:                                                       GPU Memory |
|  GPU       PID   Type   Process name                             Usage      |

That is output on my personal machine. The "Pull complete" lines are from the image components being downloaded from the registry. The next time I run this it will just instantly start up from my local system. Also, when I pull another container if it can use any of those components then they wont be downloaded again. That's one of the nice efficiencies of docker.

I'm going to stop here. In the next post I will go over some additional "tuning" you can make for your docker configuration to increase system resources for running large jobs. After that I'll start going through some usage examples for the images in NGC. I also show you how to add some nice extras to those container images like Jupyter notebook support!

Happy computing --dbk

Tags: , , ,