Python en la Línea de Comandos
Entornos virtuales, uv, pipx y ejecución de scripts de Python en Linux: cómo los operadores y desarrolladores invocan Python sin romper los paquetes del sistema.
Receta
cd billing-api
uv sync
uv run pytest -q
uv run python -m billing.cli --help
pipx install ruffCuándo usar esto:
- Configuración inicial al clonar en una máquina de desarrollo Linux o en un ejecutor de CI
- Ejecución de comandos de gestión únicos contra una base de datos de staging
- Instalación segura de CLIs globales (ruff, httpie, copier)
- Cron/systemd invocando módulos de aplicación
Ejemplo de Trabajo
#!/usr/bin/env bash
set -euo pipefail
cd /opt/billing-api
export PATH="$HOME/.local/bin:$PATH"
# El usuario de despliegue usa el entorno bloqueado
uv sync --frozen --no-dev
uv run alembic upgrade head
uv run python -m billing.worker --once
# Herramienta global sin contaminar el proyecto
pipx ensurepath
pipx install 'httpie>=3.0'#!/usr/bin/env python3
"""Script Shebang - prefiere uv run en producción."""
import sys
def main() -> int:
print("ok")
return 0
if __name__ == "__main__":
sys.exit(main())Lo que esto demuestra:
uv sync --frozencoincide exactamente con el archivo de bloqueo de CI-m modulerespeta las importaciones del paquetepipxaísla las herramientas CLI- Shebang portátil para scripts en
bin/
Análisis Profundo
Cómo Funciona
- venv -
site-packagesy enlaces simbólicos del intérprete aislados. - uv - Resolutor/instalador rápido;
uv runusa automáticamente el venv del proyecto. - pipx - venv por herramienta CLI enlazado a
~/.local/bin. - Python del sistema - Python de la distribución solo para herramientas
apt- no para dependencias de aplicaciones.
Patrones de Invocación
| Patrón | Uso |
|---|---|
uv run pytest | Comandos vinculados al proyecto |
uv tool run ruff | Herramienta efímera sin instalación |
pipx run cowsay | CLI de un solo uso |
python -m http.server | Servidor rápido de la biblioteca estándar (solo desarrollo) |
Notas de Python
# ¿Qué python estoy usando?
uv run python -c "import sys; print(sys.executable)"
# Dependencias de script PEP 723 (uv)
# /// script
# requires-python = ">=3.14"
# dependencies = ["httpx"]
# ///Trampas Comunes
sudo pip install- Rompe el gestor de paquetes del sistema. Solución: solo venv, uv o pipx.- venv incorrecto activado en cron - Usa el Python del sistema sin las dependencias necesarias. Solución: ruta absoluta a
uv runen crontab. - Shebang codificado
usr/bin/python3.11- Rompe en la actualización a 3.14. Solución:env python3+ versión documentada en README. - Mezclar poetry y uv - Dos archivos de bloqueo divergen. Solución: una cadena de herramientas por repositorio.
.venvno en .gitignore - Commit accidental. Solución: gitignore + CI crea un venv nuevo.- Actualización de pipx olvidada - Ruff global obsoleto. Solución:
pipx upgrade-alltrimestralmente.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
poetry run | Repositorios estandarizados con Poetry | El equipo está estandarizado en uv |
conda | Pila científica con dependencias binarias | Contenedores API ligeros |
docker run | Paridad exacta de producción en el portátil | Bucle rápido de edición-prueba |
pyenv | Múltiples versiones de Python localmente | Contenedores que fijan una sola versión |
Preguntas Frecuentes
¿uv o poetry para nuevos repositorios?
Este manual fija uv 0.6+ - usa uv sync y uv.lock a menos que el ADR de la organización diga lo contrario.
¿Dónde instala pipx?
~/.local/pipx/venvs con shims en ~/.local/bin - asegúrate de que PATH esté en el perfil del shell.
¿systemd ExecStart con uv?
ExecStart=/opt/billing-api/.venv/bin/uvicorn app.main:app o un script wrapper uv run.
¿PEP 668 externamente gestionado?
Debian/Ubuntu bloquean el pip del sistema - usa venv de uv, esperado en distribuciones modernas.
¿Ejecutar script sin instalar?
uv run script.py con metadatos de dependencias en línea (PEP 723).
¿Instalación editable?
uv sync con un paquete local editable en pyproject.toml - ver la documentación de entornos-empaquetado.
¿Múltiples proyectos en un servidor?
Directorios /opt/<app> separados, cada uno con su propio .venv - nunca compartir site-packages.
¿python3.14 no disponible en Ubuntu LTS?
Usa uv python install 3.14 o el PPA oficial deadsnakes según la política de la organización.
¿Correos de spam de Cron en caso de error?
Redirigir a un logger: ... 2>&1 | logger -t billing-worker.
¿Sobrescribir versión de biblioteca de pipx?
pipx inject package dependency==x.y cuando la herramienta necesita un plugin.
Relacionado
- uv - La Cadena de Herramientas Rápida - Profundidad de uv
- Gestión de Versiones de Python - Pines de versión
- Lista de Verificación de Configuración del Entorno - Onboarding
- Programación y Cron - Patrones de cron
Versiones de la Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.