Saltar al contenido

Caché de dependencias de Poetry en GitHub Actions

Última actualización

Para cachear Poetry en GitHub Actions, instale Poetry antes de actions/setup-python y, a continuación, configure cache: poetry. setup-python cachea entonces el entorno virtual de Poetry, con la clave basada en poetry.lock. El orden de los pasos es lo que suele salir mal, y es lo primero que conviene revisar si el paso de caché falla.

Opción 1: setup-python con cache: poetry

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install Poetry
        run: pipx install poetry
      - uses: actions/setup-python@v7
        with:
          python-version: "3.13"
          cache: poetry
      - run: poetry install --no-interaction
      - run: poetry run pytest

Según el README de setup-python (consultado en octubre de 2026), cache: poetry cachea los directorios de entornos virtuales, uno por cada proyecto de Poetry que encuentra, y la clave predeterminada se calcula a partir de poetry.lock. La acción ejecuta Poetry para localizar esos directorios, por lo que Poetry debe estar instalado primero. pipx viene preinstalado en las imágenes de Ubuntu alojadas por GitHub. En otros runners, instale pipx primero o use pip install poetry.

Use cache-dependency-path cuando el archivo de bloqueo esté en un subdirectorio:

- uses: actions/setup-python@v7
  with:
    python-version: "3.13"
    cache: poetry
    cache-dependency-path: services/api/poetry.lock

Opción 2: actions/cache explícito con un venv dentro del proyecto

Poetry crea por defecto los entornos virtuales en un directorio compartido (~/.cache/pypoetry/virtualenvs en Linux) con un nombre con hash. Si el venv se ubica dentro del proyecto, como .venv, obtendrá una ruta fija que cachear.

- uses: actions/checkout@v6
- run: pipx install poetry
- uses: actions/setup-python@v7
  id: py
  with:
    python-version: "3.13"
- run: poetry config virtualenvs.in-project true
- uses: actions/cache@v6
  with:
    path: .venv
    key: venv-${{ runner.os }}-py${{ steps.py.outputs.python-version }}-${{ hashFiles('poetry.lock') }}
    restore-keys: |
      venv-${{ runner.os }}-py${{ steps.py.outputs.python-version }}-
- run: poetry install --no-interaction

Tres detalles son importantes aquí:

  • La clave incluye la versión exacta de Python. steps.py.outputs.python-version devuelve la versión completa, por ejemplo 3.13.1. Un entorno virtual contiene enlaces al intérprete con el que se creó. Si la imagen del runner actualiza Python, un venv restaurado con una clave antigua quedará roto. Incluir la versión exacta en la clave fuerza una reconstrucción.
  • poetry install sigue ejecutándose. Con una coincidencia en caché, encuentra todo instalado y termina en segundos. En una restauración parcial mediante restore-keys, solo añade o actualiza lo que ha cambiado.
  • Configure virtualenvs.in-project antes del paso de caché. De lo contrario, Poetry crea el venv en otro lugar y .venv queda vacío.

Opción 3: cachear solo la caché de descargas

Si prefiere no cachear un venv, cachee la caché de descargas de Poetry y deje que poetry install reconstruya el venv en cada ejecución:

- uses: actions/cache@v6
  with:
    path: ~/.cache/pypoetry
    key: poetry-${{ runner.os }}-${{ hashFiles('poetry.lock') }}
    restore-keys: |
      poetry-${{ runner.os }}-

Es más seguro pero más lento, porque los wheels se siguen descomprimiendo en cada ejecución. Use poetry config cache-dir para confirmar la ruta real en su runner.

Qué cachear y qué no

Elemento¿Cachear?Notas
.venv dentro del proyectoSí, con la versión de Python en la claveRestauración más rápida
~/.cache/pypoetrySíSeguro, solo ahorra descargas
La instalación de Poetry en síOpcionalpipx install poetry tarda segundos
Salida de compilación dist/NoSe reconstruye en cada publicación

Fije la versión de Poetry (pipx install poetry==2.x) si cachea un venv. Una actualización de Poetry puede cambiar la estructura del entorno, y una instalación sin fijar versión deja incompleta su clave.

Cómo verificar un acierto de caché

  1. Busque Cache restored from key: ... en la salida del paso de setup-python o cache. Si no hay coincidencia, verá Cache not found for input keys: ....
  2. En la salida de poetry install, una ejecución en caliente muestra No dependencies to install or update. Una ejecución en frío lista cada paquete con Installing ....
  3. Con actions/cache explícito, bifurque según la salida durante la depuración: if: steps.cache.outputs.cache-hit != 'true' se ejecuta solo si no hay coincidencia.
  4. gh cache list --key venv- --limit 20 muestra si las entradas se están guardando.

Errores comunes

  1. Instalar Poetry después de setup-python. Con cache: poetry, la acción no encuentra Poetry y falla.
  2. No incluir poetry.lock en el repositorio. La clave se construye entonces a partir de algo sin utilidad.
  3. Falta la versión de Python en la clave del venv. Provoca errores de importación confusos tras una actualización de la imagen.
  4. Usar poetry install sin --no-interaction. Rara vez es un problema en CI, pero es una protección barata.
  5. Tratar la caché como fuente de verdad. Si algo no encaja, elimine la entrada (gh cache delete <id>) y reconstrúyala.

Para ver cómo el alcance y la expulsión afectan a todo esto, consulte Caché en GitHub Actions y límites de caché.

Preguntas frecuentes

¿Es mejor cachear .venv o el directorio de caché de Poetry?

.venv es más rápido; el directorio de caché es más seguro. Use .venv con una clave que incluya la versión exacta de Python y el hash de poetry.lock.

¿Funciona cache: poetry sin pipx?

Necesita poetry en el PATH. Cualquier método de instalación sirve siempre que se ejecute antes de setup-python.

¿Debo usar uv en lugar de Poetry en CI?

Es una decisión del proyecto. Si solo quiere instalaciones más rápidas, consulte las notas sobre uv en caché de pip.

¿Cómo guardo Poetry en caché en un monorepo?

Asigne a cada proyecto su propio cache-dependency-path y un prefijo de clave distinto, para que los cambios en un lockfile no invaliden los demás.

Próximos pasos

Para el tiempo de ejecución de pytest, consulte pruebas lentas de pytest. Para ver qué más puede mejorar, lea cómo acelerar GitHub Actions. compiler.dev le ofrece 200 minutos de prueba gratuitos para comparar su job en una máquina más rápida; consulte precios.

Ejecute esta suite de pytest en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis