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-versiondevuelve la versión completa, por ejemplo3.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 installsigue ejecutándose. Con una coincidencia en caché, encuentra todo instalado y termina en segundos. En una restauración parcial medianterestore-keys, solo añade o actualiza lo que ha cambiado.- Configure
virtualenvs.in-projectantes del paso de caché. De lo contrario, Poetry crea el venv en otro lugar y.venvqueda 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 proyecto | Sí, con la versión de Python en la clave | Restauración más rápida |
~/.cache/pypoetry | Sí | Seguro, solo ahorra descargas |
| La instalación de Poetry en sí | Opcional | pipx install poetry tarda segundos |
Salida de compilación dist/ | No | Se 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é
- 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: .... - En la salida de
poetry install, una ejecución en caliente muestraNo dependencies to install or update. Una ejecución en frío lista cada paquete conInstalling .... - Con
actions/cacheexplícito, bifurque según la salida durante la depuración:if: steps.cache.outputs.cache-hit != 'true'se ejecuta solo si no hay coincidencia. gh cache list --key venv- --limit 20muestra si las entradas se están guardando.
Errores comunes
- Instalar Poetry después de setup-python. Con
cache: poetry, la acción no encuentra Poetry y falla. - No incluir
poetry.locken el repositorio. La clave se construye entonces a partir de algo sin utilidad. - Falta la versión de Python en la clave del venv. Provoca errores de importación confusos tras una actualización de la imagen.
- Usar
poetry installsin--no-interaction. Rara vez es un problema en CI, pero es una protección barata. - 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.
Relacionado
- Cachear Cargo y compilaciones de Rust en GitHub ActionsCachee el registro de Cargo, las dependencias git y el directorio target en GitHub Actions con Swatinem/rust-cache o actions/cache, sin cachés inflados.
- Caché de módulos Go y de compilación en GitHub ActionsCachee los módulos Go (GOMODCACHE) y la caché de compilación (GOCACHE) en GitHub Actions con setup-go o actions/cache. Claves, go.sum y aciertos.
- Cachear compilaciones de Gradle en GitHub ActionsCachee las dependencias y la caché de compilación de Gradle en GitHub Actions con gradle/actions/setup-gradle o actions/cache. Claves, PR de solo lectura.
- Cachear dependencias de npm en GitHub ActionsAlmacene en caché las dependencias de npm en GitHub Actions con setup-node o actions/cache. YAML funcional, la clave correcta y por qué no node_modules.