Caché de dependencias de pip en GitHub Actions
Última actualización
Para cachear pip en GitHub Actions, configure cache: pip en actions/setup-python. Se cachea el directorio global de descargas de pip, con la clave basada en sus archivos de requisitos. Si puede cambiar a uv, astral-sh/setup-uv cachea su propio almacén e instala mucho más rápido. Ambas recetas se explican a continuación.
Opción 1: caché integrada de setup-python
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v7
with:
python-version: "3.13"
cache: pip
- run: pip install -r requirements.txt
- run: pytest
Según el README de setup-python (consultado en octubre de 2026), cache: pip cachea el directorio global de caché de pip. Por defecto, la clave se calcula a partir de requirements.txt o pyproject.toml en la raíz del repositorio. Si tiene varios archivos de requisitos, indíquelos:
- uses: actions/setup-python@v7
with:
python-version: "3.13"
cache: pip
cache-dependency-path: |
requirements.txt
requirements-dev.txt
La caché está desactivada salvo que configure cache. La clave también incluye la versión de Python y el sistema operativo, por lo que una matriz genera una entrada por cada combinación.
Opción 2: actions/cache explícito
- uses: actions/setup-python@v7
with:
python-version: "3.13"
- name: Get pip cache dir
id: pip-cache
run: echo "dir=$(pip cache dir)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
with:
path: ${{ steps.pip-cache.outputs.dir }}
key: pip-${{ runner.os }}-py3.13-${{ hashFiles('requirements*.txt') }}
restore-keys: |
pip-${{ runner.os }}-py3.13-
- run: pip install -r requirements.txt
pip cache dir devuelve la ruta correcta para cada sistema operativo (~/.cache/pip en Linux). La versión de Python debe formar parte de la clave porque las wheels compiladas se etiquetan según el intérprete.
Qué cachea pip realmente
pip almacena las wheels descargadas y, cuando compila un paquete desde el código fuente, la wheel que ha generado. Un acierto de caché en un paquete que solo existe como código fuente, como una extensión C antigua, puede ahorrar más que la descarga: evita la compilación.
| Caché | Cuándo compensa | Motivo |
|---|---|---|
| pip cache dir | Sí | Evita descargas y compilaciones locales de wheels |
Un entorno virtual (.venv) | Pocas veces | Está ligado a una compilación concreta de Python y a una ruta; falla con las actualizaciones menores |
~/.cache/pre-commit | Sí, por separado | Entornos de los hooks, con clave en .pre-commit-config.yaml |
.pytest_cache, .mypy_cache, .ruff_cache | A veces | Cachés de herramientas, no de dependencias |
Cachear un entorno virtual completo puede parecer más rápido, porque no hay nada que instalar. Pero es frágil: el entorno contiene rutas absolutas y enlaces al intérprete, así que una actualización de parche de Python en la imagen del runner puede dejarle un entorno roto. Si quiere esa velocidad, use Poetry con entornos virtuales dentro del proyecto, con clave basada en el lockfile y en la versión de Python, o use uv.
Opción 3: uv
uv es un instalador de Astral, más rápido y compatible con pip. Su acción de configuración gestiona la caché por usted.
- uses: actions/checkout@v6
- uses: astral-sh/setup-uv@v10
with:
enable-cache: true
cache-dependency-glob: |
**/pyproject.toml
**/uv.lock
- run: uv sync --frozen
- run: uv run pytest
Según el README de setup-uv (consultado en octubre de 2026), enable-cache tiene como valor por defecto auto, que activa la caché en los runners alojados por GitHub y la desactiva en los autoalojados. En runners autoalojados, incluidos los de compiler.dev, configure enable-cache: true explícitamente. setup-uv no instala su proyecto; sigue necesitando ejecutar uv sync. Para un flujo de trabajo estilo pip, uv pip install -r requirements.txt usa la misma caché.
Cómo verificar un acierto de caché
- El paso de setup-python registra
Cache restored from key: setup-python-Linux-...-pip-.... Un fallo de caché registraCache not found. - En la salida de
pip install, los paquetes restaurados desde la caché aparecen comoUsing cached ...en lugar deDownloading .... - Al final de un trabajo sin acierto de caché, el paso posterior muestra
Cache saved with key: .... gh cache list --key pip- --limit 20(o--key setup-python) muestra las entradas con su tamaño y último uso.
Errores comunes
- Sin lockfile. Un
requirements.txtcon versiones sin fijar hace que la clave no cambie mientras cambian las versiones resueltas. Fije las versiones conpip-compile,uv pip compileo un lockfile. - Calcular el hash de un archivo que no existe. Con
cache: pipy sinrequirements.txtnipyproject.toml, setup-python devuelve un error. Configurecache-dependency-path. - Compartir una misma clave entre versiones de Python. Incluya la versión en las claves explícitas; setup-python ya lo hace.
- Cachear
site-packagesdirectamente. Tiene la misma fragilidad que cachear un entorno virtual. - Guardar la caché solo en los PR. Las reglas de alcance hacen que la caché de un PR no sea visible para otros PR. Consulte Caché en GitHub Actions.
Las suites de pruebas lentas son un problema distinto de las instalaciones lentas; consulte pytest: pruebas lentas y acelerar Django en GitHub Actions.
Tamaño y límites
Las cachés de pip suelen ocupar entre 100 MB y 1 GB. Las pilas de ciencia de datos (torch, wheels de CUDA) pueden ocupar varios GB cada una y llenarán cuota de 10 GB del repositorio muy rápido. Consulte límites de caché. Si una sola wheel es enorme, plantéese si la descarga es realmente su cuello de botella.
Preguntas frecuentes
¿Debo cachear site-packages o un entorno virtual?
En general, no. Cachee el directorio de descargas de pip o use uv. Una caché de entorno virtual solo es segura si la clave incluye la versión exacta de Python y el hash del lockfile.
¿Cómo cacheo pip con varios archivos de requisitos?
Páselos todos a cache-dependency-path, uno por línea.
¿Es seguro adoptar uv solo para CI?
Lee los requirements.txt y pyproject.toml estándar. Pruebe primero con uv pip install -r requirements.txt, que cambia una sola línea.
¿Por qué la caché de pip nunca se aprovecha en una nueva rama?
Una nueva rama puede leer sus propias cachés y las de la rama predeterminada. Si main nunca guarda una, no hay nada que restaurar.
Próximos pasos
¿Usa Poetry? Lea cómo usar caché con Poetry en GitHub Actions. Para una visión más amplia, consulte cómo acelerar GitHub Actions. compiler.dev ejecuta el mismo trabajo en máquinas de 8 vCPU por $0.008 por minuto; 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.