Instalación con pip y conda, entorno virtual y config.toml

Requisitos previos

Streamlit requiere Python 3.9 o superior (recomendado 3.11 o 3.12). Antes de instalar, verifica tu versión de Python:

python --version
# Python 3.12.3

Si necesitas actualizar Python, descarga el instalador desde python.org y asegúrate de marcar la opción "Add Python to PATH" en Windows.

flowchart TD
    A["Sistema con Python 3.9+"] --> B{"Gestor de paquetes elegido?"}
    B -->|pip| C[python -m venv .venv]
    B -->|conda| D["conda create -n streamlit python=3.12"]
    C --> E[Activar entorno con scripts activate]
    D --> F[conda activate streamlit]
    E --> G[pip install streamlit]
    F --> H[conda install -c conda-forge streamlit]
    G --> I[streamlit --versión verifica instalación]
    H --> I
    I --> J["Crear .streamlit/config.toml"]
    J --> K[App lista para streamlit run]
    L[requirements.txt] --> G
    L -.->|Reproducible| M["CI/CD y producción"]

Instalación con pip y entorno virtual (recomendado)

La práctica recomendada en proyectos Python es usar un entorno virtual para aislar las dependencias de cada proyecto:

Paso 1: Crear el entorno virtual

# Navegar al directorio del proyecto
cd mi-proyecto-streamlit

# Crear entorno virtual con venv (incluido en Python 3.3+)
python -m venv .venv

Esto crea un directorio .venv/ con una instalación aislada de Python.

Paso 2: Activar el entorno virtual

# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1

# Windows (Command Prompt)
.\.venv\Scripts\activate.bat

# macOS / Linux
source .venv/bin/activate

Una vez activado, el prompt muestra (.venv) al inicio.

Paso 3: Instalar Streamlit

pip install streamlit

Para instalar una versión específica:

pip install streamlit==1.40.0

Para instalar con las dependencias opcionales más comunes:

pip install streamlit pandas numpy plotly matplotlib seaborn scikit-learn

Paso 4: Verificar la instalación

streamlit --version
# Streamlit, version 1.40.0

streamlit hello  # Abre la app de demostración oficial en el navegador

Instalación con conda (Anaconda / Miniconda)

Si usas Anaconda o Miniconda, el flujo es equivalente pero con conda:

# Crear entorno conda
conda create -n streamlit-env python=3.12

# Activar entorno
conda activate streamlit-env

# Instalar Streamlit
conda install -c conda-forge streamlit

# O con pip dentro del entorno conda
pip install streamlit

Nota: streamlit se instala desde el canal conda-forge ya que no está en el canal principal de Anaconda.

Estructura de un proyecto Streamlit

Una estructura bien organizada facilita el mantenimiento y el despliegue:

mi-proyecto/
├── .streamlit/
│   ├── config.toml      # Configuración de la app
│   └── secrets.toml     # Credenciales (NO subir a git)
├── .venv/               # Entorno virtual (NO subir a git)
├── pages/               # Páginas adicionales (apps multipágina)
│   ├── 01_analisis.py
│   └── 02_configuracion.py
├── data/                # Datos locales
│   └── dataset.csv
├── utils/               # Módulos de utilidad
│   └── procesamiento.py
├── app.py               # Punto de entrada principal
├── requirements.txt     # Dependencias del proyecto
└── .gitignore

Archivo .gitignore recomendado:

.venv/
.streamlit/secrets.toml
__pycache__/
*.pyc
.env

El archivo config.toml

El archivo .streamlit/config.toml controla el comportamiento global de la aplicación. Créalo en la raíz del proyecto (no en el directorio de usuario) para que la configuración sea específica del proyecto:

[server]
runOnSave = true          # Recarga automática al guardar
port = 8501               # Puerto por defecto
headless = true           # Sin abrir el navegador automáticamente
maxUploadSize = 200       # Tamaño máximo de subida en MB

[browser]
gatherUsageStats = false  # Desactivar telemetría

[theme]
base = "light"                      # "light" o "dark"
primaryColor = "#FF4B4B"            # Color principal de widgets
backgroundColor = "#FFFFFF"         # Fondo de la app
secondaryBackgroundColor = "#F0F2F6" # Fondo del sidebar y contenedores
textColor = "#262730"               # Color del texto
font = "sans serif"                 # "sans serif", "serif", "monospace"

[logger]
level = "info"            # "debug", "info", "warning", "error"

Gestión de dependencias con requirements.txt

Para reproducir el entorno en otro equipo o en el servidor de despliegue:

# Generar requirements.txt con las versiones instaladas
pip freeze > requirements.txt

# O crear manualmente con versiones mínimas recomendadas:

# requirements.txt
streamlit>=1.42.0
pandas>=2.2.0
numpy>=1.26.0
plotly>=5.22.0
matplotlib>=3.9.0
seaborn>=0.13.0
scikit-learn>=1.5.0

Para instalar las dependencias en otro entorno:

pip install -r requirements.txt

Ejecutar Streamlit

Una vez instalado, el comando principal es streamlit run:

streamlit run app.py

Opciones útiles:

# Puerto personalizado
streamlit run app.py --server.port 8502

# Sin abrir el navegador automáticamente
streamlit run app.py --server.headless true

# Modo de depuración (más logging)
streamlit run app.py --logger.level debug

Streamlit iniciará un servidor en http://localhost:8501 y, por defecto, abrirá la aplicación en el navegador predeterminado.

Para detener el servidor, pulsa Ctrl+C en la terminal.

Actualizar Streamlit

Streamlit pública nuevas versiones frecuentemente (cada 2-3 semanas). Para actualizar:

pip install --upgrade streamlit

Revisa el changelog oficial antes de actualizar en proyectos en producción para asegurarte de que no hay cambios que rompan la compatibilidad.

Contexto: por qué un entorno virtual es obligatorio, no opcional

Mucha gente empieza instalando Streamlit con pip install streamlit en el Python global del sistema. Funciona al principio, pero genera problemas serios en cuanto tienes más de un proyecto: las dependencias de una app pueden entrar en conflicto con las de otra, y actualizar pandas para un proyecto puede romper otro que dependía de una versión concreta. Los entornos virtuales (venv o conda) resuelven este problema creando una instalación Python aislada por proyecto.

Además, los entornos virtuales son imprescindibles para el despliegue: cuando subes tu app a Streamlit Community Cloud o a un servidor Docker, el entorno del servidor se construye a partir de tu requirements.txt. Si tu máquina local mezcla dependencias globales con las del proyecto, pip freeze generará un archivo incompleto o con basura que romperá el build remoto.

Explicación línea por línea del flujo recomendado

1. python -m venv .venv crea un directorio .venv/ con su propio intérprete Python y su propio pip. El módulo venv forma parte de la librería estándar desde Python 3.3.
2. La activación (.venv\Scripts\activate en Windows o source .venv/bin/activate en Unix) modifica la variable PATH para que python y pip apunten al entorno virtual.
3. pip install streamlit instala Streamlit y todas sus dependencias (pandas, numpy, pyarrow, tornado, altair...) dentro del .venv/, sin tocar el Python global.
4. streamlit --versión verifica que el comando está disponible y muestra la versión instalada.
5. streamlit hello lanza la aplicación de ejemplo oficial, útil para confirmar que todo funciona antes de empezar a escribir código propio.

Tabla de comandos esenciales

| Comando | Descripción | |---------|-------------| | python -m venv .venv | Crea entorno virtual | | .venv\Scripts\activate | Activa entorno (Windows) | | source .venv/bin/activate | Activa entorno (macOS/Linux) | | deactivate | Desactiva el entorno actual | | pip install streamlit | Instala la última versión | | pip install streamlit==1.40.0 | Instala versión específica | | pip install --upgrade streamlit | Actualiza Streamlit | | pip freeze > requirements.txt | Exporta dependencias | | pip install -r requirements.txt | Instala desde requirements | | streamlit --versión | Muestra versión instalada | | streamlit hello | Lanza app de demo | | streamlit run app.py | Ejecuta tu app | | streamlit config show | Imprime config.toml efectivo |

Errores comunes

streamlit: command not found. El entorno virtual no está activado o Streamlit se instaló en el Python global. Activa el venv con source .venv/bin/activate y reinstala si es necesario.

Versiones incompatibles de Python. Streamlit 1.40+ requiere Python 3.9 o superior. Si usas Python 3.8, obtendrás errores al importar el paquete. Actualiza Python o usa una versión antigua de Streamlit.

Conflictos con pyarrow. Algunos entornos corporativos bloquean pyarrow por cuestiones de seguridad. Si ves errores sobre pyarrow al instalar Streamlit, instala primero pip install "pyarrow>=14" y luego Streamlit.

Espacios en rutas de instalación. En Windows, rutas con espacios (C:\Users\Juan Pérez\...) pueden causar problemas con algunos scripts. Prefiere rutas sin espacios para el directorio del proyecto.

Entorno virtual confundido. Si accidentalmente activas el entorno virtual equivocado, Python usará un paquete diferente al esperado. Confirma con pip show streamlit qué entorno está activo antes de instalar.

Mejores prácticas

• Nunca instales Streamlit globalmente: siempre usa un entorno virtual por proyecto.
• Incluye .venv/, .streamlit/secrets.toml, __pycache__/ y *.pyc en .gitignore.
• Mantén requirements.txt sincronizado con pip freeze antes de cada commit importante o despliegue.
• Fija las versiones mayores en requirements.txt (por ejemplo, streamlit>=1.42,<2.0) para evitar rupturas inesperadas por versiones futuras con cambios breaking.
• Documenta en el README los pasos para reproducir el entorno desde cero, incluyendo la versión de Python requerida.
• Si trabajas en equipo, considera usar Poetry o uv como alternativas modernas a venv + pip para una gestión de dependencias más robusta.