Getting Started with the NGC SDK

Prerequisites

Python version >= 3.10

Install from pypi

You can install the package from pypi.org by running the following command:

pip install ngcsdk

This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.

After you install the SDK, your first step is to create and configure the client.

Creating and configuring NGC SDK client

The first time that you use the SDK, you must set your configuration. To set your configuration, run the following functions.

Tip

You will need your API key. For information about generating an API key, refer to the setup, https://ngc.nvidia.com/setup.

>>> from ngcsdk import Client
>>> clt = Client()
>>> clt.configure(api_key='****NkMQ', org_name='nvidia', team_name='no-team')
Validating configuration...
Successfully validated configuration.
>>> clt.current_config()
[{'key': 'apikey', 'value': '****NkMQ', 'source': 'user settings'},
 {'key': 'format_type', 'value': 'ascii', 'source': 'user settings'},
 {'key': 'org', 'value': 'nvidia', 'source': 'user settings'},
 {'key': 'team', 'value': 'no-team', 'source': 'user settings'}]

Guest mode

Artifacts that are publicly available on the NGC catalog can be listed, inspected, and downloaded without an API key. The client enters guest mode automatically when no API key is configured, and the registry APIs transparently use the public endpoints.

>>> from ngcsdk import Client
>>> clt = Client()
>>> clt.config.is_guest_mode
True
>>> clt.registry.model.download_version(
...     "nvidia/nemo/commandrecognition_en_matchboxnet3x1x64_v1:1.0.0rc1",
...     destination="./checkpoints",
... )

The client is in guest mode only when no API key is found. The key is resolved from, in order of precedence: the value passed to configure(), the NGC_CLI_API_KEY environment variable, and the config file written by ngc config set (~/.ngc/config). A key left over from an earlier ngc config set is enough to take you out of guest mode, which typically surfaces as an authentication error such as Invalid SAK key or Missing org - If Authenticated, org is also required.

To force guest mode regardless of any existing configuration, pass the no-* sentinel values. These clear the attribute for the current client only; the config file on disk is not modified.

>>> clt = Client()
>>> clt.configure(api_key="no-apikey", org_name="no-org", team_name="no-team")
>>> clt.config.is_guest_mode
True
>>> clt.current_config()
[{'key': 'format_type', 'value': 'json', 'source': 'global argument'}]

Note

configure(api_key=None) does not clear a configured key — the previous value is retained. Use api_key="no-apikey" to remove it.

Debugging

Configure debug logging using Python's logging utility.

>>> import logging
>>> from ngcsdk import Client
>>> logger = logging.getLogger()
>>> logger.setLevel(logging.DEBUG)
>>> clt = Client()
>>> model = clt.registry.model.info("nvidia/nemotron")
DEBUG:ngcbase.api.connection:Requesting URL (GET): https://api.stg.ngc.nvidia.com/v2/org/nvidia/model/nemotron
    payload: None
    params: None
DEBUG:ngcbase.api.authentication:Retrieving API Key Token from cache....
DEBUG:ngcbase.api.authentication:Token in use: ****hPWE
DEBUG:ngcbase.api.authentication:Expiration time of token: '2024-03-07 16:36:03.849188'
DEBUG:ngcbase.api.authentication:Fetched token from the cache. Expires 2024-03-07 16:36:03.849188
DEBUG:ngcbase.api.utils:Headers:
DEBUG:ngcbase.api.utils:{'Content-Type': 'application/json', ...}
DEBUG:ngcbase.api.connection:Response status: 200 - Reason: OK
DEBUG:ngcbase.api.connection:Time taken to process URL: https://api.stg.ngc.nvidia.com/v2/org/nvidia/model/nemotron: 0.34587s
DEBUG:ngcbase.api.connection:Response is: {"requestStatus":{"statusCode":"SUCCESS"}, ...}

For more information on how to configure logging, see Python's official tutorial on logging.

Output

Methods return either objects or JSON. Objects can be inspected and converted to a python dictionary or JSON format.

>>> from ngcsdk import Client
>>> clt = Client()
>>> model = clt.registry.model.info("nvidia/nemotron")
>>> help(model)
Help on Model in module ngccli.data.api.Model object:

class Model(builtins.object)
 |  Model(propDict=None)
 |
 |  Methods defined here:
 |
 |  __init__(self, propDict=None)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |
 |  isValid(self)
 |
 |  toDict(self)
 |
 |  toJSON(self, pretty=False)

>>> model.toDict()
{'name': 'nvidia/nemotron', ...}
>>> model.toJSON()
'{"name": "nvidia/nemotron", ...}

>>> models = clt.registry.model.list()
>>> help(models)
Help on chain object:

class chain(builtins.object)
 |  chain(*iterables) --> chain object
 |
 |  Return a chain object whose .__next__() method returns elements from the
 |  first iterable until it is exhausted, then elements from the next
 |  iterable, until all of the iterables are exhausted.
 |
 |  Methods defined here:
 |
 |  __getattribute__(self, name, /)
 |      Return getattr(self, name).
 |
 |  __iter__(self, /)
 |      Implement iter(self).
 |
 |  __next__(self, /)
 |      Implement next(self).

>>> [model.name for model in models]
['nvidia/nemotron', ....]