From b7fb12453362a847d7252c49188355092484bc86 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Wed, 24 Jun 2026 16:05:12 -0400 Subject: [PATCH 1/2] Add spec page for archive file formats --- learn/specifications/packages/file-formats.md | 56 +++++++++++++++++-- 1 file changed, 50 insertions(+), 6 deletions(-) diff --git a/learn/specifications/packages/file-formats.md b/learn/specifications/packages/file-formats.md index 517d8fb3..2b80e14a 100644 --- a/learn/specifications/packages/file-formats.md +++ b/learn/specifications/packages/file-formats.md @@ -1,14 +1,58 @@ --- sidebar_position: 50 --- + # Package file formats -:::note[Work in Progress] -This part of the ecosystem is not fully standardized yet. +This document describes the archive file formats used for conda artifacts distribution: `.tar.bz2` and `.conda`. + +## Nomenclature + +- Archive: A compressed file which, once extracted, may result in one or more files and/or directories. +- Artifact: The distributable file that is produced as a result of a build process. It happens to be an archive. When used as "conda artifact", it is meant to encompass both `.tar.bz2` and `.conda` archive file formats. +- Tarball: A file that has been produced by running `tar` on a set of files. The resulting `.tar` file MAY be further compressed into another file format (e.g. `.gz` or `.bz2`), and may be still called compressed tarball or simply tarball. +- Package: Roughly speaking, a distributable artifact that ships executables, libraries or resources needed to support the execution of programs. It may refer to the compressed archive, or its extracted form, without further distinction. The emphasis is on the distributed contents, not so much on the form. + +## Specification + +conda packages, whose contents are described and standardized in [CEP 34](./cep-0034.md), MAY be archived and distributed in two formats: + +- `.tar.bz2`: The first generation of conda archives. Referred to as version 1. +- `.conda`: The second generation of conda archives. Referred to as version 2. + +### `.tar.bz2` + +To produce a `.tar.bz2` file, the conda package directory as described in [CEP 34](./cep-0034.md) MUST be first archived into an uncompressed tarball (`.tar`). The root level of the archive MUST match the root level of the target location once installed (i.e. no intermediate subdirectories). The resulting tarball MUST be then compressed using the BZ2 compression scheme. The filename MUST follow [CEP 26](./cep-0026.md), with a `.tar.bz2` extension. Namely: `{name}-{version}-{build}.tar.bz2`. + +For example, given a package directory `project-1.2.3-0/`, GNU `tar` can be used like this: + +```bash +cd project-1.2.3-0/ +tar cvjf project-1.2.3-0.tar.bz2 . +``` + +The resulting tarball `project-1.2.3-0.tar.bz2` can be extracted using: + +```bash +tar xvf project-1.2.3-0.tar.bz2 +``` + +### `.conda` + +A `.conda` artifact MUST be a ZIP file whose filename follows [CEP 26](./cep-0026.md) with a `.conda` extension (i.e. `{name}-{version}-{build}.conda`). It MUST NOT be compressed. The ZIP archive MUST contain two Zstandard-compressed tarballs and a JSON document, named as: + +- `info-{name}-{version}-{build}.tar.zst` +- `pkg-{name}-{version}-{build}.tar.zst` +- `metadata.json` + +Each tarball MUST be named with the above syntax, taking the `name`, `version` and `build` values from the `info/index.json` file as described in [CEP 34](./cep-0034.md). + +The `info-*` tarball MUST contain the full `info/` folder as described in [CEP 34](./cep-0034.md). The `pkg-*` tarball MUST carry everything else in the package directory. The root level of the tarballs MUST match the root level of the target location once installed (i.e. no intermediate subdirectories). + +The `metadata.json` MUST be a JSON document that ships a dictionary following this schema: -Some preliminary information can be found at: +- `conda_pkg_format_version: int`. The version of the `.conda` file format. Currently `2`. -- https://docs.conda.io/projects/conda-build/en/stable/resources/package-spec.html. +## History -It will cover the details of `.tar.bz2` and `.conda` file formats. -::: +- 2026-03-04: [CEP 35](/learn/ceps/cep-0035) is approved, standardizing `.tar.bz2` and `.conda` archive file formats. From ecf8b925075a3cc45093d07c3fd159d423220e0f Mon Sep 17 00:00:00 2001 From: jaimergp Date: Wed, 24 Jun 2026 16:15:38 -0400 Subject: [PATCH 2/2] Link to spec pages --- learn/specifications/packages/file-formats.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/learn/specifications/packages/file-formats.md b/learn/specifications/packages/file-formats.md index 2b80e14a..7b69f20c 100644 --- a/learn/specifications/packages/file-formats.md +++ b/learn/specifications/packages/file-formats.md @@ -15,14 +15,14 @@ This document describes the archive file formats used for conda artifacts distri ## Specification -conda packages, whose contents are described and standardized in [CEP 34](./cep-0034.md), MAY be archived and distributed in two formats: +conda packages MAY be archived and distributed in two formats: - `.tar.bz2`: The first generation of conda archives. Referred to as version 1. - `.conda`: The second generation of conda archives. Referred to as version 2. ### `.tar.bz2` -To produce a `.tar.bz2` file, the conda package directory as described in [CEP 34](./cep-0034.md) MUST be first archived into an uncompressed tarball (`.tar`). The root level of the archive MUST match the root level of the target location once installed (i.e. no intermediate subdirectories). The resulting tarball MUST be then compressed using the BZ2 compression scheme. The filename MUST follow [CEP 26](./cep-0026.md), with a `.tar.bz2` extension. Namely: `{name}-{version}-{build}.tar.bz2`. +To produce a `.tar.bz2` file, the conda package contents MUST be first archived into an uncompressed tarball (`.tar`). The root level of the archive MUST match the root level of the target location once installed (i.e. no intermediate subdirectories). The resulting tarball MUST be then compressed using the BZ2 compression scheme. The [filename](../distribution/package-identifiers.md) MUST have a `.tar.bz2` extension. Namely: `{name}-{version}-{build}.tar.bz2`. For example, given a package directory `project-1.2.3-0/`, GNU `tar` can be used like this: @@ -39,15 +39,15 @@ tar xvf project-1.2.3-0.tar.bz2 ### `.conda` -A `.conda` artifact MUST be a ZIP file whose filename follows [CEP 26](./cep-0026.md) with a `.conda` extension (i.e. `{name}-{version}-{build}.conda`). It MUST NOT be compressed. The ZIP archive MUST contain two Zstandard-compressed tarballs and a JSON document, named as: +A `.conda` artifact MUST be a ZIP file with a [filename](../distribution/package-identifiers.md) using the `.conda` extension (i.e. `{name}-{version}-{build}.conda`). It MUST NOT be compressed. The ZIP archive MUST contain two Zstandard-compressed tarballs and a JSON document, named as: - `info-{name}-{version}-{build}.tar.zst` - `pkg-{name}-{version}-{build}.tar.zst` - `metadata.json` -Each tarball MUST be named with the above syntax, taking the `name`, `version` and `build` values from the `info/index.json` file as described in [CEP 34](./cep-0034.md). +Each tarball MUST be named with the above syntax, taking the `name`, `version` and `build` values from the [`info/index.json` file](../packages/info.md). -The `info-*` tarball MUST contain the full `info/` folder as described in [CEP 34](./cep-0034.md). The `pkg-*` tarball MUST carry everything else in the package directory. The root level of the tarballs MUST match the root level of the target location once installed (i.e. no intermediate subdirectories). +The `info-*` tarball MUST contain the [full `info/` folder](../packages/info.md). The `pkg-*` tarball MUST carry everything else in the package directory. The root level of the tarballs MUST match the root level of the target location once installed (i.e. no intermediate subdirectories). The `metadata.json` MUST be a JSON document that ships a dictionary following this schema: