Skip to main content
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: 
image = await contree.images.use("ubuntu:latest")
result = await image.run(shell="echo hello")

​
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(): 
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.

​
Methods

  • 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. 
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.
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: 
result = await image.run(shell="pip install mylib && python setup.py", tag="myapp:ready", disposable=False)
print(result.tag)  # "myapp:ready"

​
Listing Images

View all available images in your ConTree instance: 
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.