Working with Images

ConTree SDK provides several ways to reference and import container images. For full API documentation, see ImagesManager and ImagesManagerSync.

Using Images by Tag

The simplest way to get an image is images.use(tag). This creates an image object immediately without any API call — the tag is resolved at execution time when you run a command:

Async
Sync

image = await contree.images.use("ubuntu:latest")
result = await image.run(shell="echo hello")

image = contree.images.use("ubuntu:latest")
result = image.run(shell="echo hello").wait()

Pulling Images

For resolving a tag/UUID to an image upfront, use images.use(strict=True). For importing images from external registries, use images.oci():

Async
Sync

print(f"Selected {image_uuid=}")
print(f"Selected {image_tag=}")

print("\nPulling by UUID (strict):")
result = await client.images.use(image_uuid, strict=True)
print(f"Pulled by UUID: {result.uuid=}, {result.tag=}, {result.state=}")

print("\nPulling by tag (strict):")
result = await client.images.use(image_tag, strict=True)
print(f"Pulled by tag: {result.uuid=}, {result.tag=}, {result.state=}")

print("\nImporting public image using oci:")
result = await client.images.oci("docker://ghcr.io/linuxserver/code-server:latest")
print(f"Pulled public: {result.uuid=}, {result.tag=}, {result.state=}")

See use() and oci() for all parameters.

print(f"Selected {image_uuid=}")
print(f"Selected {image_tag=}")

print("\nPulling by UUID (strict):")
result = client.images.use(image_uuid, strict=True)
print(f"Pull by UUID: {result.uuid=}, {result.tag=}, {result.state=}")

print("\nPulling by tag (strict):")
result = client.images.use(image_tag, strict=True)
print(f"Pull by tag: {result.uuid=}, {result.tag=}, {result.state=}")

print("\nImporting public image using oci:")
result = client.images.oci("docker://ghcr.io/linuxserver/code-server:latest")
print(f"Import public: {result.uuid=}, {result.tag=}, {result.state=}")

See use() and oci() for all parameters.

Methods

Async
Sync

use()(ref) — no API call; tag or UUID is resolved at execution time
use()(ref, strict=True) — verifies the image exists via an API call
oci()(ref) (aliases: docker(), podman(), pull_by_oci()) — like use(strict=True), but imports from the registry if not found locally
import_from()(ref) — always imports from an external registry

use()(ref) — no API call; tag or UUID is resolved at execution time
use()(ref, strict=True) — verifies the image exists via an API call
oci()(ref) (aliases: docker(), podman(), pull_by_oci()) — like use(strict=True), but imports from the registry if not found locally
import_from()(ref) — always imports from an external registry

import_from always triggers a new import operation and should only be used when you explicitly need to re-import. In most cases, prefer images.oci(), which returns an existing image if already imported. If no import is needed at all, use images.use().

What `ref` can be

UUID — reference an existing image by its UUID, e.g. "550e8400-e29b-41d4-a716-446655440000" or UUID(...)
OCI tag — reference by image tag, e.g. "ubuntu:latest"
OCI full URL — full reference including registry host, e.g. "docker://ghcr.io/owner/image:tag"
OCIReference — programmatic OCI reference object

Tagging Images

You can assign or remove a tag on any image using tag_as() and untag(). Tags are unique across all images — assigning an existing tag to a new image moves it automatically.

Async
Sync

image = await client.images.use(image_tag, strict=True)
print(f"Original: {image.uuid=}, {image.tag=}")

tagged = await image.tag_as("my-custom-tag:v1")
print(f"After tag_as: {tagged.uuid=}, {tagged.tag=}")

untagged = await tagged.untag()
print(f"After untag: {untagged.uuid=}, {untagged.tag=}")

result = await image.run(shell="echo hello", tag="my-result:v1", disposable=False)
print(f"Run result: {result.uuid=}, {result.tag=}")

See tag_as() and untag() for details.

image = client.images.use(image_tag, strict=True)
print(f"Original: {image.uuid=}, {image.tag=}")

tagged = image.tag_as("my-custom-tag:v1")
print(f"After tag_as: {tagged.uuid=}, {tagged.tag=}")

untagged = tagged.untag()
print(f"After untag: {untagged.uuid=}, {untagged.tag=}")

result = image.run(shell="echo hello", tag="my-result:v1", disposable=False).wait()
print(f"Run result: {result.uuid=}, {result.tag=}")

See tag_as() and untag() for details.

You can also tag the result of a run() directly by passing tag= to the call — the resulting image will be tagged after execution completes:

Async
Sync

result = await image.run(shell="pip install mylib && python setup.py", tag="myapp:ready", disposable=False)
print(result.tag)  # "myapp:ready"

result = image.run(shell="pip install mylib && python setup.py", tag="myapp:ready", disposable=False).wait()
print(result.tag)  # "myapp:ready"

Listing Images

View all available images in your ConTree instance:

Async
Sync

all_images = await client.images()
print(f"Loaded {all_images=}")

limited_images = await client.images(number=3)
print(f"Found {len(limited_images)=}")

tagged_images = await client.images(tagged=True)
print(f"Found {len(tagged_images)=}")

imported_images = await client.images(kind=ImageKind.IMPORTED)
print(f"Found {len(imported_images)=}")

recent_images = await client.images(since=datetime.now() - timedelta(days=7), number=5)
print(f"Found {len(recent_images)=}")

See ImagesManager for filtering and iteration options.

all_images = client.images()
print(f"Loaded {all_images=}")

limited_images = client.images(number=3)
print(f"Found {len(limited_images)=}")

tagged_images = client.images(tagged=True)
print(f"Found {len(tagged_images)=}")

imported_images = client.images(kind=ImageKind.IMPORTED)
print(f"Found {len(imported_images)=}")

recent_images = client.images(since=datetime.now() - timedelta(days=7), number=5)
print(f"Found {len(recent_images)=}")

See ImagesManagerSync for filtering and iteration options.

Get Started

Inference

Observability

Post-training

Data Lab

Sandboxes

Teams & Access Management

Other Capabilities

Integrations

Using Images by Tag

Pulling Images

Methods

What `ref` can be

Tagging Images

Listing Images

​Using Images by Tag

​Pulling Images

​Methods

​What ref can be

​Tagging Images

​Listing Images

Using Images by Tag

Pulling Images

Methods

What `ref` can be

Tagging Images

Listing Images