Skip to main content

CEP 22 - Frozen environments

Title CEP 22 - Frozen environments
Status Draft
Author(s) Jaime Rodríguez-Guerra <jaime.rogue@gmail.com>
Created Nov 19, 2024
Updated Apr 3, 2025
Discussion https://github.com/conda/ceps/pull/99
Implementation NA

Abstract​

Given a $CONDA_PREFIX/conda-meta/frozen marker file, tools will prevent modifications in $CONDA_PREFIX unless a special override flag is passed.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119 when, and only when, they appear in all capitals, as shown here.

Motivation​

This CEP is inspired by PEP 668, which defines the EXTERNALLY-MANAGED marker file for Python virtual environments. The conda ecosystem could benefit from a similar file for conda environments. Some examples include:

  • Protecting modifications of the base environment in conda installations.
  • Protecting external management of .pixi/envs/* environments by other tools.
  • Reproducibility of the build and host environments in conda package building tools.

Specification​

  • The marker file path MUST be $CONDA_PREFIX/conda-meta/frozen. This is case-sensitive.
  • The marker file can be empty. It MAY contain a JSON document with schema {"message": str}. This is, an object with a single message key mapped to a non-empty string.
  • Tools MUST respect the presence of frozen in the environment and error out with:
    • A message chosen by the tool, if frozen is empty.
    • The message included in the message key, if frozen is not empty.
    • A help message explaining how to override the check, if available.
  • Tools SHOULD offer a way to override the presence of frozen (e.g. --override-frozen-env). However, tools MUST NOT offer ways to enable the overrides by default.

Example​

An example frozen file can be:

{
    "message": "This environment is running a production service.\nIt is marked as read-only and MUST not be modified."
}

A hypothetical tool finding this file in the environment to be modified would output something like the following and then exit:

Could not modify environment. The environment has been marked as frozen. Reason:

    This environment is running a production service.
    It is marked as read-only and MUST not be modified.

You can bypass this check by using the `--override-frozen-env-checks` flag, at your own risk.

Rationale​

The conda-meta/ directory has been chosen as a target location for the marker file so packages cannot dictate whether a conda environment is frozen or not. Such a state should be governed by the initial state of the installation and user configuration choices. That said, a package could still rely on post-link scripts to freeze a conda environment upon installation.

This CEP only standardizes how conda ecosystem tools handle the presence of conda-meta/frozen in conda environments. More specifically, it does not attempt to block how Python packaging tools like pip, uv or poetry interact with a conda environment. If users want to really protect their conda environment from Python packaging tools, they should also resort to mechanisms like PEP 668.

References​

  • conda-protect is a conda plugin that implements similar ideas.
  • conda-pypi is a prototype conda plugin that showcases how to install an EXTERNALLY-MANAGED file in a conda environment.

All CEPs are explicitly CC0 1.0 Universal.