diff --git a/ansible/roles/gitea-actions/templates/Containerfile.espidf.j2 b/ansible/roles/gitea-actions/templates/Containerfile.espidf.j2
index fe2a61d..b849d61 100644
--- a/ansible/roles/gitea-actions/templates/Containerfile.espidf.j2
+++ b/ansible/roles/gitea-actions/templates/Containerfile.espidf.j2
@@ -1,11 +1,16 @@
 # ESP-IDF firmware job image (managed by ansible: roles/gitea-actions).
-# Adds node (required by actions/checkout and other JS actions) and the AWS CLI
-# (firmware artifacts ship to S3) on top of the official Espressif toolchain.
+# Adds node (required by actions/checkout and other JS actions), the AWS CLI
+# (firmware artifacts ship to S3), and the common-yaml header generator's Python
+# deps on top of the official Espressif toolchain.
 # IDF lives at /opt/esp/idf — firmware jobs source /opt/esp/idf/export.sh.
+# python3-yaml + python3-jinja2 are installed as distro packages so the
+# common-yaml generator runs with a plain `python3 generate.py` — no pip at job
+# time (the base image's system Python is PEP 668 externally-managed) and no
+# need to source the IDF venv just to generate headers.
 FROM espressif/idf:{{ esp_idf_version }}
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
-        curl ca-certificates unzip \
+        curl ca-certificates unzip python3-yaml python3-jinja2 \
     && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
     && apt-get install -y --no-install-recommends nodejs \
     && rm -rf /var/lib/apt/lists/*