Cómo instalar paquetes de Python sin conexión a Internet

Instalar paquetes de Python sin conexión es una necesidad frecuente en servidores aislados, laboratorios, redes corporativas restringidas y equipos que no pueden acceder directamente a PyPI. Aunque el comando pip install suele descargar todo desde Internet, pip también permite preparar previamente los archivos necesarios, copiarlos a la máquina desconectada e instalar las dependencias desde una carpeta local. El proceso es sencillo cuando se planifica correctamente.

Antes de comenzar, conviene comprender cómo funcionan los entornos virtuales con venv, cómo instalar bibliotecas con pip, cómo se organiza un paquete instalable de Python y cuándo utilizar Poetry para gestionar dependencias. Estos conceptos ayudan a evitar conflictos entre versiones.

Cómo funciona una instalación offline

La idea consiste en utilizar un equipo con Internet para descargar ruedas binarias, archivos fuente y dependencias. Después se copia esa carpeta a la máquina aislada mediante una memoria USB, una red interna o un repositorio corporativo. Finalmente, pip recibe las opciones --no-index y --find-links para buscar exclusivamente en la carpeta local.

Es importante preparar los archivos usando una versión de Python y un sistema operativo compatibles con el equipo de destino. Una rueda creada para Windows no funciona necesariamente en Linux, y un paquete compilado para Python 3.12 puede no servir en Python 3.10.

Crear un entorno virtual

python -m venv .venv

En Windows, actívalo con:

.venv\Scripts\activate

En macOS o Linux:

source .venv/bin/activate

El entorno virtual mantiene las dependencias del proyecto separadas de las bibliotecas globales. Esto facilita repetir la instalación y reduce el riesgo de modificar herramientas utilizadas por el sistema.

Preparar un archivo requirements.txt

En el equipo conectado crea un archivo con versiones explícitas:

requests==2.32.3
pandas==2.2.3
openpyxl==3.1.5

Fijar versiones mejora la reproducibilidad. Sin versiones, una descarga realizada hoy puede producir un conjunto distinto al preparado dentro de varios meses. También puedes generar el archivo desde un entorno existente:

python -m pip freeze > requirements.txt

Sin embargo, freeze incluye todo lo instalado. Revisa el resultado para no transportar dependencias innecesarias.

Descargar todos los paquetes

Crea una carpeta y utiliza pip download:

mkdir paquetes
python -m pip download -r requirements.txt -d paquetes

Pip descarga las dependencias transitivas, es decir, los paquetes requeridos por las bibliotecas principales. La documentación oficial de pip download explica las opciones para elegir plataforma, implementación y versión de Python cuando el equipo de descarga es diferente al destino.

Comprueba el contenido de la carpeta. Lo ideal es obtener archivos .whl, porque las ruedas se instalan sin compilar. Los archivos .tar.gz pueden requerir compiladores, encabezados del sistema y herramientas adicionales en la máquina aislada.

Descargar únicamente ruedas binarias

python -m pip download \
  -r requirements.txt \
  -d paquetes \
  --only-binary=:all:

Si una dependencia no ofrece rueda compatible, el comando fallará. Ese fallo es útil porque revela el problema antes de copiar los archivos. Puedes buscar una versión que sí tenga rueda, preparar una rueda propia o instalar previamente las herramientas de compilación en el destino.

Instalar en el equipo sin Internet

Copia la carpeta paquetes y el archivo requirements.txt. Luego ejecuta:

python -m pip install \
  --no-index \
  --find-links=paquetes \
  -r requirements.txt

En PowerShell o CMD puedes escribir el comando en una sola línea. --no-index impide que pip consulte PyPI, mientras que --find-links indica dónde están los archivos locales. La referencia oficial de pip install describe estas opciones y el proceso de resolución de dependencias.

Verificar la instalación

python -m pip check
python -m pip list

pip check informa dependencias incompatibles o ausentes. Después ejecuta una prueba real:

import requests
import pandas
import openpyxl

print("Dependencias disponibles")

No basta con comprobar que pip terminó sin errores. Algunos paquetes cargan bibliotecas nativas únicamente cuando se importan o cuando se utiliza una función específica.

Preparar archivos para otra plataforma

Pip permite descargar ruedas para un destino diferente:

python -m pip download \
  --platform win_amd64 \
  --python-version 311 \
  --implementation cp \
  --abi cp311 \
  --only-binary=:all: \
  -r requirements.txt \
  -d paquetes-windows

Este método exige conocer exactamente la plataforma, el ABI y la implementación. Si eliges parámetros incorrectos, pip puede descargar archivos que el destino rechazará. Cuando sea posible, realiza la descarga en una máquina equivalente o dentro de una máquina virtual con la misma configuración.

Crear un pequeño repositorio interno

Para varios equipos no conviene distribuir carpetas manualmente cada vez. Una organización puede mantener un directorio compartido o un índice privado. La estructura más simple consiste en almacenar ruedas aprobadas en una ruta accesible:

python -m pip install \
  --no-index \
  --find-links=\\servidor\python-packages \
  paquete_interno

En ambientes más grandes pueden utilizarse herramientas como devpi, Artifactory o Nexus. Un repositorio interno permite auditar versiones, retirar paquetes vulnerables y controlar qué dependencias llegan a producción.

Validar integridad y seguridad

No descargues archivos desde sitios desconocidos. Obtén los paquetes desde PyPI, el repositorio oficial del proveedor o una fuente corporativa validada. Puedes guardar hashes en el archivo de requisitos:

requests==2.32.3 \
  --hash=sha256:HASH_ESPERADO

Después instala con --require-hashes. Este enfoque detecta archivos modificados y obliga a declarar todas las dependencias. En sistemas sensibles, conserva además un registro de la fecha, el origen y la persona que aprobó cada paquete.

Errores frecuentes

El error “No matching distribution found” suele indicar que falta una rueda compatible o que se descargó para otra versión de Python. Un fallo durante la compilación muestra que pip recibió un archivo fuente y no encuentra compilador o encabezados. Los conflictos de versiones aparecen cuando dos paquetes exigen rangos incompatibles. También es común copiar únicamente la biblioteca principal y olvidar dependencias transitivas.

Otra causa de problemas es utilizar el comando pip de una instalación distinta. Prefiere siempre python -m pip, porque así la instalación queda asociada al intérprete que ejecutará el proyecto.

Flujo recomendado para equipos

1. Crear un entorno limpio.
2. Definir versiones en requirements.txt.
3. Descargar ruedas compatibles.
4. Ejecutar una instalación de prueba en una máquina equivalente.
5. Comprobar con pip check y pruebas automatizadas.
6. Copiar los archivos y sus hashes al entorno aislado.
7. Documentar exactamente el comando utilizado.

Conclusión

Instalar paquetes de Python sin Internet no requiere soluciones improvisadas. Con pip download, ruedas compatibles, versiones fijadas y una instalación mediante --no-index, puedes reproducir un entorno completo de forma controlada. Para proyectos pequeños basta una carpeta local; para empresas, un repositorio privado ofrece trazabilidad y seguridad. La clave es preparar y probar todo antes de llevarlo a la máquina desconectada.