Instalación del SDK de Python de Mistral
En esta página
Prerrequisitos
Actualizado el 2 de noviembre de 2026 — SDK de Mistral 3. Esta lección cubría anteriormente la versión 2 del SDK y Python 3.9. La versión actual es la 3.7.0 (lanzada el 1 de noviembre de 2026); requiere Python 3.10 o superior, y el cliente se importa mediante
from mistralai.client import Mistraldesde la versión 2.0 (marzo de 2026). Fuentes: mistralai en PyPI · notas de la versión v2.0.0 · notas de la versión v3.0.0.
La instalación del SDK requiere tres elementos: Python 3.10 o superior, que puedes verificar con python --version; un pip actualizado, que obtendrás con pip install --upgrade pip; y tu clave de API de Mistral ya configurada como variable de entorno, tal como se explicó en la lección anterior. Si aún no tienes Python instalado en tu máquina, descarga la última versión estable desde python.org o utiliza el gestor de paquetes de tu sistema.
Aísla tu proyecto antes de instalar nada
Trabaja siempre dentro de un entorno virtual. Este hábito te ahorrará un dolor de cabeza muy común: tener dos proyectos en la misma máquina, donde uno requiere una versión específica del SDK y el otra una diferente, y que un único pip install rompa silenciosamente el primer proyecto al actualizar el segundo. Un entorno virtual proporciona a cada proyecto sus propias dependencias aisladas, separadas de los paquetes globales del sistema.
# Crear el entorno virtual
python -m venv mistral-env
# Activar en Linux / macOS
source mistral-env/bin/activate
# Activar en Windows
mistral-env\Scripts\activate
Una vez activado, el indicador de tu terminal llevará el prefijo del nombre del entorno entre paréntesis: (mistral-env). Este pequeño marcador garantiza que los comandos posteriores se apliquen en la ubicación correcta; si no aparece, no instales nada.
Instalación del SDK oficial
Instalar el SDK de Mistral requiere un solo comando:
pip install mistralai
Esto instala la última versión del SDK: la 3.7.0 a fecha de 1 de noviembre de 2026. La generación 3 comenzó con la versión 3.0, lanzada el 28 de septiembre de 2026. Para confirmar que todo está en su sitio, ejecuta pip show mistralai para mostrar el nombre del paquete, la versión y las dependencias.
A veces un proyecto requiere una versión concreta, por ejemplo, para mantener a todo un equipo alineado durante una migración. Puedes especificar restricciones en dos niveles:
# Mantenerse dentro de la generación 3
pip install "mistralai>=3,<4"
# Instalar una versión exacta
pip install "mistralai==3.7.0"
Durante el proceso, pip descarga algunas dependencias que aparecen en la lista. Es útil reconocerlas, especialmente httpx2, el cliente HTTP que gestiona las llamadas de red (el SDK utiliza este en lugar de httpx a partir de la versión 3.0), y pydantic, que valida y serializa los datos intercambiados. No interactuarás directamente con ellas, pero su presencia explica por qué una instalación que parece pequeña ocupa aún así unos pocos megabytes.
Verifica la instalación con una llamada real a la API
Ejecutar pip show demuestra que el paquete existe, no que tu configuración funcione. La prueba real consulta la API. Crea un archivo llamado test_mistral.py:
import os
from mistralai.client import Mistral
api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
print("Error: La variable de entorno MISTRAL_API_KEY no está configurada.")
else:
client = Mistral(api_key=api_key)
print("¡Cliente de Mistral inicializado correctamente!")
# Listar modelos disponibles
models = client.models.list()
print(f"Modelos disponibles: {len(models.data)}")
for model in models.data[:5]:
print(f" - {model.id}")
Luego ejecútalo:
python test_mistral.py
Este script verifica dos cosas a la vez. La comprobación de api_key distingue inmediatamente una variable de entorno faltante de un problema de red genuino; sin ella, podrías pasar diez minutos sospechando de tu cortafuegos cuando lo único que ocurrió es que se reabrió el terminal sin la variable. Si se muestra la lista de modelos, el SDK está instalado correctamente y tu clave es aceptada por la API.
Haz reproducible el entorno
En un proyecto de equipo, la instalación debe ser reproducible. Congela tus dependencias:
pip freeze > requirements.txt
Tus compañeros podrán entonces reconstruir exactamente el mismo entorno con un solo comando:
pip install -r requirements.txt
Tu servidor de despliegue también leerá este archivo. Adquiere el hábito de regenerarlo cada vez que añadas una biblioteca; de lo contrario, el código funcionará en tu máquina y en ninguna otra.
Cuatro fallos comunes y cómo diagnosticarlos
El error ModuleNotFoundError: No module named mistralai casi siempre significa que el terminal no está usando el entorno virtual correcto. Verifícalo con which python, que debería apuntar a tu venv, y luego con pip list | grep mistralai.
El error ImportError: cannot import name 'Mistral' from 'mistralai' indica código escrito para la versión 1 del SDK. Desde la versión 2.0, todas las importaciones se realizan a través de mistralai.client: escribe from mistralai.client import Mistral. La lección sobre versiones del SDK detalla otros cambios.
Un error de SSL o de red a menudo revela la presencia de un proxy corporativo entre tú y el exterior. Indica explícitamente a pip dónde está:
pip install mistralai --proxy http://proxy.entreprise.com:8080
Por último, si la instalación rechaza tu versión de Python, recuerda que el SDK requiere como mínimo Python 3.10 desde la versión 2.0. Actualiza Python o instala pyenv para ejecutar múltiples versiones simultáneamente sin tocar el intérprete del sistema.
Puntos clave
- Instala el SDK con
pip install mistralaidentro de un entorno virtual - La versión actual es la 3.7.0 (1 de noviembre de 2026); importa el cliente mediante
from mistralai.client import Mistral - Verifica la instalación listando los modelos disponibles
- Congela las dependencias en
requirements.txtpara garantizar la reproducibilidad - Se requiere Python 3.10 o superior