Saltar al contenido

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 compensaMotivo
pip cache dirSíEvita descargas y compilaciones locales de wheels
Un entorno virtual (.venv)Pocas vecesEstá ligado a una compilación concreta de Python y a una ruta; falla con las actualizaciones menores
~/.cache/pre-commitSí, por separadoEntornos de los hooks, con clave en .pre-commit-config.yaml
.pytest_cache, .mypy_cache, .ruff_cacheA vecesCaché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é

  1. El paso de setup-python registra Cache restored from key: setup-python-Linux-...-pip-.... Un fallo de caché registra Cache not found.
  2. En la salida de pip install, los paquetes restaurados desde la caché aparecen como Using cached ... en lugar de Downloading ....
  3. Al final de un trabajo sin acierto de caché, el paso posterior muestra Cache saved with key: ....
  4. gh cache list --key pip- --limit 20 (o --key setup-python) muestra las entradas con su tamaño y último uso.

Errores comunes

  1. Sin lockfile. Un requirements.txt con versiones sin fijar hace que la clave no cambie mientras cambian las versiones resueltas. Fije las versiones con pip-compile, uv pip compile o un lockfile.
  2. Calcular el hash de un archivo que no existe. Con cache: pip y sin requirements.txt ni pyproject.toml, setup-python devuelve un error. Configure cache-dependency-path.
  3. Compartir una misma clave entre versiones de Python. Incluya la versión en las claves explícitas; setup-python ya lo hace.
  4. Cachear site-packages directamente. Tiene la misma fragilidad que cachear un entorno virtual.
  5. 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.

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

Pruébelo gratis