Archives and portable workspaces

Workspace archives package a project into a portable .tar.zst, .tar.gz, or .tar.bz2 archive that includes the manifest and source files. An existing or newly generated lockfile can also be included, along with resolved conda package artifacts for offline deployment and receipts for integrity checks.

conda workspace archive -o my-project.tar.zst

When -o / --output is omitted, the archive is written in the workspace root using the workspace name as the filename stem. That default name must be a single filename segment. Use -o / --output for other paths.

In git repos, only tracked files are included. Built-in exclusions (.git, __pycache__, .conda/envs, .pixi, and common credential material such as .env, .ssh, .aws, and .npmrc) always apply. Configure additional exclusions in the manifest:

[workspace.archive]
exclude = ["docs/**", "*.log"]

Or pass them on the command line:

conda workspace archive --exclude "benchmarks/**"

Restoring archives

Extract an archive and install environments in one step:

conda workspace unarchive my-project.tar.zst --target ./restored --install

The extraction target path must be absent. Existing files, links, and directories, including empty directories, are not overwritten.

Install one archived environment to a final runtime prefix, optionally under a staged filesystem root:

conda workspace unarchive my-project.tar.zst \
  --install \
  --dest /tmp/rootfs \
  -e runtime \
  --prefix /opt/runtime

When --dest is used, unarchive warns if installed files still reference the physical staging prefix.

Locking, bundling, and receipts

Pass --lock to solve and update the lockfile before archiving:

conda workspace archive --lock

For offline deployment, --bundle includes resolved conda package archives (.conda or .tar.bz2) inside the archive. Package hashes are verified against the lockfile on bundling and before receipt-verified cache priming:

conda workspace archive --lock --bundle --receipt -o offline.tar.zst
CONDA_OFFLINE=true conda workspace unarchive offline.tar.zst --receipt --install

For handoff workflows that need a separate integrity record, --receipt writes an external in-toto Statement JSON file. unarchive --receipt verifies the archive, extracted manifest, extracted lockfile, and lockfile package inventory before moving the verified workspace into place:

conda workspace archive --lock --receipt -o my-project.tar.zst
conda workspace unarchive my-project.tar.zst --receipt --target ./verified

Python integrations can use conda_workspaces.archive.WorkspaceArchive for the same archive operations without importing CLI handlers.

See the archive tutorial for a full CLI walkthrough, Use workspace archives from Python for integration examples, and the archive receipt reference for the receipt JSON format.