Use workspace archives from Python

Use conda_workspaces.archive.WorkspaceArchive when another Python tool needs archive behavior without shelling out to conda workspace archive or importing CLI handlers.

Create an archive

Create an archive from the current workspace:

from conda_workspaces.archive import WorkspaceArchive

archive = WorkspaceArchive.create(
    output="dist/my-project.tar.zst",
    receipt=True,
)

Pass workspace= to archive a different workspace root:

archive = WorkspaceArchive.create(
    workspace="/path/to/workspace",
    output="dist/my-project.tar.zst",
    receipt="dist/my-project.receipt.json",
)

Set lock=True to refresh conda.lock before writing the archive, and bundle=True to include resolved package archives from conda’s package cache:

archive = WorkspaceArchive.create(
    output="dist/my-project-offline.tar.zst",
    lock=True,
    bundle=True,
    receipt=True,
)

Inspect and verify an archive

Inspect archive metadata without extracting files:

archive = WorkspaceArchive("dist/my-project.tar.zst", receipt=True)
info = archive.inspect()

if not info["has_manifest"]:
    raise RuntimeError("not a workspace archive")

Verify an archive against its receipt:

receipt = archive.verify()
print(receipt.workspace_paths)

Receipt verification checks the archive digest before extraction. It does not identify who created the archive or receipt.

Extract an archive

Extract into an empty or missing target directory:

result = archive.extract(target="/tmp/restored", require_sha256=True)

print(result.target)
print(result.verified)

When a bundled archive has a verified receipt, extraction can prime the local conda package cache from packages stored inside the archive. Without a receipt, bundled packages are left in the extracted workspace and cache priming is skipped.

Pass prime_cache=False to disable cache priming:

archive.extract(target="/tmp/restored", prime_cache=False)

Install from an archive

Install all archived environments after extraction:

archive.install(target="/tmp/restored")

Install one environment to an explicit runtime prefix:

archive.install(
    target="/tmp/restored",
    environment="runtime",
    prefix="/opt/runtime",
)

Stage files under a filesystem root while preserving the requested runtime prefix:

result = archive.install(
    target="/tmp/restored",
    environment="runtime",
    prefix="/opt/runtime",
    dest="/tmp/rootfs",
)

if result.prefix_reference_matches:
    print("Some files still reference the staging prefix")

prefix_reference_matches reports files that still contain the physical staging prefix after installation. It is a warning signal for relocation workflows, not an automatic prefix-rewrite feature.

Customize installation

Pass install_handler= when an integration wants conda-workspaces to extract and verify an archive, but wants to control environment installation:

from pathlib import Path


def install_handler(
    workspace: Path,
    environment: str | None,
    prefix: Path | None,
    target_prefix_override: str | None,
) -> int:
    print(workspace, environment, prefix, target_prefix_override)
    return 0


archive.install(
    target="/tmp/restored",
    environment="runtime",
    prefix="/opt/runtime",
    dest="/tmp/rootfs",
    install_handler=install_handler,
)

The handler receives the extracted workspace path, the selected environment, the physical install prefix, and the runtime prefix override when staging under dest.

API reference

See Archives for the formal API reference.