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

# Working with Images

ConTree SDK provides several ways to reference and import container images. For full API documentation, see [`ImagesManager`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager) and [`ImagesManagerSync`](./reference/images#contree_sdk.sdk.managers.images.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:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    image = await contree.images.use("ubuntu:latest")
    result = await image.run(shell="echo hello")
    ```
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = contree.images.use("ubuntu:latest")
    result = image.run(shell="echo hello").wait()
    ```
  </Tab>
</Tabs>

## 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()`:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    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()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.use) and [`oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.oci) for all parameters.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    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()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.use) and [`oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.oci) for all parameters.
  </Tab>
</Tabs>

### Methods

<Tabs>
  <Tab title="Async">
    * [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.use)(ref) — no API call; tag or UUID is resolved at execution time
    * [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.use)(ref, strict=True) — verifies the image exists via an API call
    * [`oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.oci)(ref) (aliases: [`docker()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.docker), [`podman()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.podman), [`pull_by_oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.pull_by_oci)) — like `use(strict=True)`, but imports from the registry if not found locally
    * [`import_from()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager.import_from)(ref) — always imports from an external registry
  </Tab>

  <Tab title="Sync">
    * [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.use)(ref) — no API call; tag or UUID is resolved at execution time
    * [`use()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.use)(ref, strict=True) — verifies the image exists via an API call
    * [`oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.oci)(ref) (aliases: [`docker()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.docker), [`podman()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.podman), [`pull_by_oci()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.pull_by_oci)) — like `use(strict=True)`, but imports from the registry if not found locally
    * [`import_from()`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync.import_from)(ref) — always imports from an external registry
  </Tab>
</Tabs>

<Danger>
  `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()`.
</Danger>

### 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`](./reference/oci#contree_sdk.utils.oci.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.

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    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()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.tag_as) and [`untag()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.untag) for details.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    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()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.tag_as) and [`untag()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.untag) for details.
  </Tab>
</Tabs>

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:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    result = await image.run(shell="pip install mylib && python setup.py", tag="myapp:ready", disposable=False)
    print(result.tag)  # "myapp:ready"
    ```
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    result = image.run(shell="pip install mylib && python setup.py", tag="myapp:ready", disposable=False).wait()
    print(result.tag)  # "myapp:ready"
    ```
  </Tab>
</Tabs>

## Listing Images

View all available images in your ConTree instance:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    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`](./reference/images#contree_sdk.sdk.managers.images.ImagesManager) for filtering and iteration options.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    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`](./reference/images#contree_sdk.sdk.managers.images.ImagesManagerSync) for filtering and iteration options.
  </Tab>
</Tabs>