Skip to content

Manage Cloud application versions

Info

Learn the concepts and fundamentals of versions in the Explanation page.

An app version represents a specific executable code. You can think of a version like a Git commit tag. It is a snapshot of the code at a specific point in time.

This how-to guide explains how to interact with versions using methods on the Application class. These methods return a Version object. Go the reference section to see all the available parameters for each method.

Create a version

Use the Application.new_version method to create a new version for an application.

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="humming-cricket")
version = app.new_version()

nextmv.write(version.to_dict())

uv run main.py

{
  "id": "version-yvp7wirx",
  "application_id": "humming-cricket",
  "name": "version-yvp7wirx",
  "description": "",
  "executable": {
    "id": "version-yvp7wirx",
    "user_email": "sebastian@nextmv.io",
    "uploaded_at": "2026-07-28T18:37:41.624957Z",
    "requirements": {
      "executable_type": "python",
      "runtime": "ghcr.io/nextmv-io/runtime/python:3.11"
    }
  },
  "created_at": "2026-07-28T18:37:53.273646Z",
  "updated_at": "2026-07-28T18:37:53.273646Z"
}

The call above will create a random ID, and use the same identifier for the version name. The name of the version is used as a human-readable label. You can use the id and/or name keyword arguments to specify a custom ID and name for the version. For example:

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="humming-cricket")
version = app.new_version(id="v0.0.1", name="Initial version")

nextmv.write(version.to_dict())

uv run main.py

{
  "id": "v0.0.1",
  "application_id": "humming-cricket",
  "name": "Initial version",
  "description": "",
  "executable": {
    "id": "v0.0.1",
    "user_email": "sebastian@nextmv.io",
    "uploaded_at": "2026-07-28T18:37:41.624957Z",
    "requirements": {
      "executable_type": "python",
      "runtime": "ghcr.io/nextmv-io/runtime/python:3.11"
    }
  },
  "created_at": "2026-07-28T18:38:00.967991Z",
  "updated_at": "2026-07-28T18:38:00.967991Z"
}

In automated workflows, you don't have to check if a version exists before creating it. Use the exist_ok keyword argument to avoid an error if the version already exists:

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="humming-cricket")
version = app.new_version(id="v0.0.1", exist_ok=True)

nextmv.write(version.to_dict())

uv run main.py

{
  "id": "v0.0.1",
  "application_id": "humming-cricket",
  "name": "Initial version",
  "description": "",
  "executable": {
    "id": "v0.0.1",
    "user_email": "sebastian@nextmv.io",
    "uploaded_at": "2026-07-28T18:37:41.624957Z",
    "requirements": {
      "executable_type": "python",
      "runtime": "ghcr.io/nextmv-io/runtime/python:3.11"
    }
  },
  "created_at": "2026-07-28T18:38:00.967991Z",
  "updated_at": "2026-07-28T18:38:00.967991Z"
}

Get a version

Use the Application.version method to retrieve an existing version for an application by its ID.

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="humming-cricket")
version = app.version(version_id="v0.0.1")

nextmv.write(version.to_dict())

uv run main.py

{
  "id": "v0.0.1",
  "application_id": "humming-cricket",
  "name": "Initial version",
  "description": "",
  "executable": {
    "id": "v0.0.1",
    "user_email": "sebastian@nextmv.io",
    "uploaded_at": "2026-07-28T18:37:41.624957Z",
    "requirements": {
      "executable_type": "python",
      "runtime": "ghcr.io/nextmv-io/runtime/python:3.11"
    }
  },
  "created_at": "2026-07-28T18:38:00.967991Z",
  "updated_at": "2026-07-28T18:38:00.967991Z"
}

You can list all versions in the application using the Application.list_versions method. The same information is displayed as for the individual versions, but as a list of objects.

import json
import os

from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="humming-cricket")
versions = app.list_versions()

print(json.dumps([version.to_dict() for version in versions], indent=2))

uv run main.py

[
  {
    "id": "v0.0.1",
    "application_id": "humming-cricket",
    "name": "Initial version",
    "description": "",
    "executable": {
      "id": "v0.0.1",
      "user_email": "sebastian@nextmv.io",
      "uploaded_at": "2026-07-28T18:37:41.624957Z",
      "requirements": {
        "executable_type": "python",
        "runtime": "ghcr.io/nextmv-io/runtime/python:3.11"
      }
    },
    "created_at": "2026-07-28T18:38:00.967991Z",
    "updated_at": "2026-07-28T18:38:00.967991Z"
  },
  ...
  {
    "id": "version-yvp7wirx",
    "application_id": "humming-cricket",
    "name": "version-yvp7wirx",
    "description": "",
    "executable": {
      "id": "version-yvp7wirx",
      "user_email": "sebastian@nextmv.io",
      "uploaded_at": "2026-07-28T18:37:41.624957Z",
      "requirements": {
        "executable_type": "python",
        "runtime": "ghcr.io/nextmv-io/runtime/python:3.11"
      }
    },
    "created_at": "2026-07-28T18:37:53.273646Z",
    "updated_at": "2026-07-28T18:37:53.273646Z"
  }
]

For automated workflows, you can check if a version exists with the Application.version_exists method. The method returns True if the version exists, and False if it does not.

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="humming-cricket")
exists = app.version_exists(version_id="v0.0.1")

nextmv.write({"exists": exists})

uv run main.py

{
  "exists": true
}

Update a version

You can update different attributes of a version using the Application.update_version method, such as its:

  • Name
  • Description

Please note that you cannot change the executable associated with a version or the version ID. Once a version is created, the executable code will always be attached to this version no matter how many other ones are published. This is, the code is versioned. You can create as many versions from an executable as you want.

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="humming-cricket")
version = app.update_version(
    version_id="v0.0.1",
    name="Beta deliverable",
    description="Pre-alpha launch",
)

nextmv.write(version.to_dict())

uv run main.py

{
  "id": "v0.0.1",
  "application_id": "humming-cricket",
  "name": "Beta deliverable",
  "description": "Pre-alpha launch",
  "executable": {
    "id": "v0.0.1",
    "user_email": "sebastian@nextmv.io",
    "uploaded_at": "2026-07-28T18:37:41.624957Z",
    "requirements": {
      "executable_type": "python",
      "runtime": "ghcr.io/nextmv-io/runtime/python:3.11"
    }
  },
  "created_at": "2026-07-28T18:38:00.967991Z",
  "updated_at": "2026-07-28T18:38:32.771019Z"
}

Delete a version

Warning

Deleting a version is irreversible. All the version's data will be permanently deleted.

Delete a version using the Application.delete_version method.

import os

from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="humming-cricket")
app.delete_version(version_id="v0.0.1")

uv run main.py