> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nebius AI Cloud SDK for Python

The Nebius AI Cloud SDK for Python is a client library for working with Nebius AI Cloud resources from Python applications.

For the Python SDK documentation, see:

* [Nebius AI Cloud repository for the Python SDK](https://github.com/nebius/pysdk)
* [Python SDK reference](https://nebius.github.io/pysdk/apiReference.html)

## Supported Python versions

The SDK supports Python 3.10 and later.

If your project uses SDK version 0.2.x, check the migration notes in the [Python SDK repository](https://github.com/nebius/pysdk#migration-from-02x-to-03x) before updating to version 0.3.x or later.

## Installation and update

<Tip>
  Before installing the SDK, consider creating a [Python virtual environment](https://docs.python.org/3/library/venv.html) for your project to avoid dependency conflicts.
</Tip>

Install the SDK package:

```bash theme={null}
python3 -m pip install nebius
```

If you installed the SDK earlier, update it to the latest version:

```bash theme={null}
python3 -m pip install -U nebius
```

## Initialization and authentication

For server-to-server communication, use a [service account](/iam/overview#accounts-and-members) to authenticate SDK requests. The SDK uses the service account credentials to generate a JSON Web Token, exchange it for an IAM token and refresh the IAM token in the background.

1. [Create a service account](/iam/service-accounts/manage#creating-a-service-account).

2. Create a private and public key pair:

   ```bash theme={null}
   openssl genrsa -out private.pem 4096 && \
   openssl rsa -in private.pem -outform PEM -pubout -out public.pem
   ```

   This command creates the `private.pem` and `public.pem` files in the current directory.

3. Upload the public key to create an authorized key:

   ```bash theme={null}
   nebius iam auth-public-key create \
     --account-service-account-id <service_account_ID> \
     --data "$(cat public.pem)"
   ```

   In the command, specify the service account ID.

4. Initialize the SDK with the private key file:

   ```python theme={null}
   from nebius.sdk import SDK

   sdk = SDK(
       user_agent_prefix="<application_name>/<application_version_or_comment>",
       service_account_private_key_file_name="<private_key_file_path>",
       service_account_public_key_id="<public_key_ID>",
       service_account_id="<service_account_ID>",
   )
   ```

   The `SDK` constructor initializes the SDK and uses the service account private key file to authenticate requests.

   The `user_agent_prefix` argument adds a prefix to the [User-Agent header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/User-Agent) sent with each request. Use `user_agent_prefix` to identify your application in the list of requests. The version or comment in the prefix is optional.

   In the script, set the following parameters:

   * `<application_name>/<application_version_or_comment>`: Application or library that calls the SDK. The version or comment is optional.
   * `<private_key_file_path>`: Path to the private key file, for example `private.pem`.
   * `<public_key_ID>`: ID of the public key generated for the service account.
   * `<service_account_ID>`: ID of your service account.

<Note>
  For user-to-server communication, authenticate SDK requests by using an IAM token, CLI configuration or a credentials file. For more information about authentication methods, see the [Python SDK repository](https://github.com/nebius/pysdk#how-to).
</Note>

## Sending a request

The SDK provides service clients grouped by Nebius AI Cloud services and API versions.

Many mutating operations, such as creating, updating and deleting resources, return an operation object. If an operation is asynchronous, call `wait` to wait until it is completed.

The following example creates a [Compute virtual machine (VM)](/compute/).

1. Create a Python file with the following code.

   This script already includes SDK initialization and authentication.

   ```python theme={null}
   import asyncio

   from nebius.api.nebius.common.v1 import ResourceMetadata
   from nebius.api.nebius.compute.v1 import (
       AttachedDiskSpec,
       CreateDiskRequest,
       CreateInstanceRequest,
       DiskServiceClient,
       DiskSpec,
       ExistingDisk,
       InstanceServiceClient,
       InstanceSpec,
       IPAddress,
       NetworkInterfaceSpec,
       ResourcesSpec,
       SourceImageFamily,
   )
   from nebius.sdk import SDK


   async def create_instance() -> None:
       # Initialize the SDK with the service account private key file.
       sdk = SDK(
           user_agent_prefix="<application_name>/<application_version_or_comment>",
           service_account_private_key_file_name="<private_key_file_path>",
           service_account_public_key_id="<public_key_ID>",
           service_account_id="<service_account_ID>",
       )

       async with sdk:
           disk_service = DiskServiceClient(sdk)
           instance_service = InstanceServiceClient(sdk)

           # Create the boot disk.
           disk_operation = await disk_service.create(
               CreateDiskRequest(
                   metadata=ResourceMetadata(
                       parent_id="<project_ID>",
                       name="my-boot-disk",
                   ),
                   spec=DiskSpec(
                       size_gibibytes=93,
                       type=DiskSpec.DiskType.NETWORK_SSD,
                       source_image_family=SourceImageFamily(
                           image_family="<image_family_name>",
                       ),
                   ),
               )
           )

           await disk_operation.wait()

           # Create the VM that uses the boot disk.
           instance_operation = await instance_service.create(
               CreateInstanceRequest(
                   metadata=ResourceMetadata(
                       parent_id="<project_ID>",
                       name="my-vm",
                   ),
                   spec=InstanceSpec(
                       resources=ResourcesSpec(
                           platform="<platform_name>",
                           preset="<preset_name>",
                       ),
                       network_interfaces=[
                           NetworkInterfaceSpec(
                               name="eth0",
                               subnet_id="<subnet_ID>",
                               ip_address=IPAddress(),
                           ),
                       ],
                       boot_disk=AttachedDiskSpec(
                           attach_mode=AttachedDiskSpec.AttachMode.READ_WRITE,
                           existing_disk=ExistingDisk(
                               id=disk_operation.resource_id,
                           ),
                           device_id="boot-disk",
                       ),
                   ),
               )
           )

           await instance_operation.wait()


   if __name__ == "__main__":
       asyncio.run(create_instance())
   ```

   In the script, set the following parameters:

   * `<application_name>/<application_version_or_comment>`: Application or library that calls the SDK. For more information, see [Initialization and authentication](#initialization-and-authentication).
   * `<private_key_file_path>`: Path to the private key file.
   * `<public_key_ID>`: ID of the public key generated for the service account.
   * `<service_account_ID>`: ID of your service account.
   * `<project_ID>`: ID of the project where you create the resources.
   * `<image_family_name>`: Name of the [boot disk image family](/compute/storage/boot-disk-images), for example `ubuntu24.04-driverless`.
   * `<platform_name>`: Name of the [Compute platform](/compute/virtual-machines/types), for example `cpu-e2`.
   * `<preset_name>`: Name of the resource preset. Available presets depend on the selected platform, for example `2vcpu-8gb` for `cpu-e2`.
   * `<subnet_ID>`: ID of the VM's [subnet](/vpc/overview#subnet).

2. Execute the file:

   ```bash theme={null}
   python3 <file_name>.py
   ```

After you run the example, delete the VM and its boot disk if you no longer need them. Otherwise, Compute continues [charging](/compute/resources/pricing) for these resources.