Python no Shell

Ambientes virtuais, uv, pipx, e execução de scripts Python no Linux - como operadores e desenvolvedores invocam Python sem quebrar pacotes do sistema.

Receita

cd billing-api
uv sync
uv run pytest -q
uv run python -m billing.cli --help
pipx install ruff

Quando usar isso:

Configuração inicial de clone em máquina de desenvolvimento Linux ou runner de CI
Execução de comandos de gerenciamento únicos contra o banco de dados de staging
Instalação segura de CLIs globais (ruff, httpie, copier)
Cron/systemd invocando módulos da aplicação

Exemplo de Trabalho

#!/usr/bin/env bash
set -euo pipefail
cd /opt/billing-api
export PATH="$HOME/.local/bin:$PATH"
 
# Usuário de deploy usa ambiente travado
uv sync --frozen --no-dev
uv run alembic upgrade head
uv run python -m billing.worker --once
 
# Ferramenta global sem poluir o projeto
pipx ensurepath
pipx install 'httpie>=3.0'

#!/usr/bin/env python3
"""Script Shebang - prefira uv run em produção."""
import sys
 
def main() -> int:
    print("ok")
    return 0
 
if __name__ == "__main__":
    sys.exit(main())

O que isso demonstra:

uv sync --frozen corresponde exatamente ao lockfile da CI
-m module respeita as importações do pacote
pipx isola ferramentas CLI
Shebang portátil para scripts em bin/

Mergulho Profundo

Como Funciona

venv - site-packages e links simbólicos do interpretador isolados.
uv - Resolver/instalador rápido; uv run usa automaticamente o venv do projeto.
pipx - venv por ferramenta CLI vinculado a ~/.local/bin.
Python do sistema - Python da distribuição apenas para ferramentas apt - não para dependências de aplicativos.

Padrões de Invocação

Padrão	Uso
`uv run pytest`	Comandos vinculados ao projeto
`uv tool run ruff`	Ferramenta efêmera sem instalação
`pipx run cowsay`	CLI de uso único
`python -m http.server`	Servidor rápido da stdlib (apenas dev)

Notas Python

# Qual python estou usando?
uv run python -c "import sys; print(sys.executable)"
 
# Dependências de script PEP 723 (uv)
# /// script
# requires-python = ">=3.14"
# dependencies = ["httpx"]
# ///

Armadilhas

sudo pip install - Quebra o gerenciador de pacotes do sistema. Correção: use apenas venv, uv ou pipx.
Venv errado ativado no cron - Usa o python do sistema sem as dependências necessárias. Correção: caminho absoluto para uv run no crontab.
Shebang fixo /usr/bin/python3.11 - Quebra na atualização para 3.14. Correção: env python3 + versão documentada no README.
Misturar poetry e uv - Dois lockfiles divergem. Correção: uma toolchain por repositório.
.venv não está no .gitignore - Commit acidental. Correção: gitignore + CI cria um venv novo.
Upgrade do pipx esquecido - ruff global desatualizado. Correção: pipx upgrade-all trimestralmente.

Alternativas

Alternativa	Use Quando	Não Use Quando
`poetry run`	Repositórios padronizados com Poetry	Equipe padronizada em uv
`conda`	Pilha científica com dependências binárias	Contêineres API enxutos
`docker run`	Paridade exata de produção no laptop	Loop rápido de edição-teste
`pyenv`	Múltiplas versões do Python localmente	Contêiner fixa uma única versão

FAQs

uv ou poetry para novos repositórios?

Este cookbook fixa uv 0.6+ - use uv sync e uv.lock a menos que o ADR da organização diga o contrário.

Onde o pipx instala?

~/.local/pipx/venvs com shims em ~/.local/bin - garanta que o PATH esteja no perfil do shell.

systemd ExecStart com uv?

ExecStart=/opt/billing-api/.venv/bin/uvicorn app.main:app ou um script wrapper uv run.

PEP 668 externamente gerenciado?

Debian/Ubuntu bloqueiam o pip do sistema - use venv do uv, esperado em distribuições modernas.

Executar script sem instalar?

uv run script.py com metadados de dependência inline (PEP 723).

Instalação editável?

uv sync com pacote local editável em pyproject.toml - veja a documentação de environments-packaging.

Múltiplos projetos em um servidor?

Diretórios /opt/<app> separados, cada um com seu próprio .venv - nunca compartilhe site-packages.

python3.14 não disponível no Ubuntu LTS?

Use uv python install 3.14 ou o PPA deadsnakes oficial, de acordo com a política da organização.

Spam de e-mail do Cron em caso de erro?

Redirecione para o logger: ... 2>&1 | logger -t billing-worker.

Sobrescrever versão de biblioteca no pipx?

pipx inject package dependency==x.y quando a ferramenta precisar de um plugin.

Relacionados

uv - A Toolchain Rápida - Profundidade do uv
Gerenciando Versões do Python - Pins de versão
Checklist de Configuração de Ambiente - Onboarding
Agendamento e Cron - Padrões de cron

Versões das Pilhas: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+, e uv 0.6+.

Python no Shell

Ambientes virtuais, uv, pipx, e execução de scripts Python no Linux - como operadores e desenvolvedores invocam Python sem quebrar pacotes do sistema.

Receita

cd billing-api
uv sync
uv run pytest -q
uv run python -m billing.cli --help
pipx install ruff

Quando usar isso:

Configuração inicial de clone em máquina de desenvolvimento Linux ou runner de CI
Execução de comandos de gerenciamento únicos contra o banco de dados de staging
Instalação segura de CLIs globais (ruff, httpie, copier)
Cron/systemd invocando módulos da aplicação

Exemplo de Trabalho

#!/usr/bin/env bash
set -euo pipefail
cd /opt/billing-api
export PATH="$HOME/.local/bin:$PATH"
 
# Usuário de deploy usa ambiente travado
uv sync --frozen --no-dev
uv run alembic upgrade head
uv run python -m billing.worker --once
 
# Ferramenta global sem poluir o projeto
pipx ensurepath
pipx install 'httpie>=3.0'

#!/usr/bin/env python3
"""Script Shebang - prefira uv run em produção."""
import sys
 
def main() -> int:
    print("ok")
    return 0
 
if __name__ == "__main__":
    sys.exit(main())

O que isso demonstra:

uv sync --frozen corresponde exatamente ao lockfile da CI
-m module respeita as importações do pacote
pipx isola ferramentas CLI
Shebang portátil para scripts em bin/

Mergulho Profundo

Como Funciona

venv - site-packages e links simbólicos do interpretador isolados.
uv - Resolver/instalador rápido; uv run usa automaticamente o venv do projeto.
pipx - venv por ferramenta CLI vinculado a ~/.local/bin.
Python do sistema - Python da distribuição apenas para ferramentas apt - não para dependências de aplicativos.

Padrões de Invocação

Padrão	Uso
`uv run pytest`	Comandos vinculados ao projeto
`uv tool run ruff`	Ferramenta efêmera sem instalação
`pipx run cowsay`	CLI de uso único
`python -m http.server`	Servidor rápido da stdlib (apenas dev)

Notas Python

# Qual python estou usando?
uv run python -c "import sys; print(sys.executable)"
 
# Dependências de script PEP 723 (uv)
# /// script
# requires-python = ">=3.14"
# dependencies = ["httpx"]
# ///

Armadilhas

sudo pip install - Quebra o gerenciador de pacotes do sistema. Correção: use apenas venv, uv ou pipx.
Venv errado ativado no cron - Usa o python do sistema sem as dependências necessárias. Correção: caminho absoluto para uv run no crontab.
Shebang fixo /usr/bin/python3.11 - Quebra na atualização para 3.14. Correção: env python3 + versão documentada no README.
Misturar poetry e uv - Dois lockfiles divergem. Correção: uma toolchain por repositório.
.venv não está no .gitignore - Commit acidental. Correção: gitignore + CI cria um venv novo.
Upgrade do pipx esquecido - ruff global desatualizado. Correção: pipx upgrade-all trimestralmente.

Alternativas

Alternativa	Use Quando	Não Use Quando
`poetry run`	Repositórios padronizados com Poetry	Equipe padronizada em uv
`conda`	Pilha científica com dependências binárias	Contêineres API enxutos
`docker run`	Paridade exata de produção no laptop	Loop rápido de edição-teste
`pyenv`	Múltiplas versões do Python localmente	Contêiner fixa uma única versão

FAQs

uv ou poetry para novos repositórios?

Este cookbook fixa uv 0.6+ - use uv sync e uv.lock a menos que o ADR da organização diga o contrário.

Onde o pipx instala?

~/.local/pipx/venvs com shims em ~/.local/bin - garanta que o PATH esteja no perfil do shell.

systemd ExecStart com uv?

ExecStart=/opt/billing-api/.venv/bin/uvicorn app.main:app ou um script wrapper uv run.

PEP 668 externamente gerenciado?

Debian/Ubuntu bloqueiam o pip do sistema - use venv do uv, esperado em distribuições modernas.

Executar script sem instalar?

uv run script.py com metadados de dependência inline (PEP 723).

Instalação editável?

uv sync com pacote local editável em pyproject.toml - veja a documentação de environments-packaging.

Múltiplos projetos em um servidor?

Diretórios /opt/<app> separados, cada um com seu próprio .venv - nunca compartilhe site-packages.

python3.14 não disponível no Ubuntu LTS?

Use uv python install 3.14 ou o PPA deadsnakes oficial, de acordo com a política da organização.

Spam de e-mail do Cron em caso de erro?

Redirecione para o logger: ... 2>&1 | logger -t billing-worker.

Sobrescrever versão de biblioteca no pipx?

pipx inject package dependency==x.y quando a ferramenta precisar de um plugin.

Relacionados

uv - A Toolchain Rápida - Profundidade do uv
Gerenciando Versões do Python - Pins de versão
Checklist de Configuração de Ambiente - Onboarding
Agendamento e Cron - Padrões de cron

Versões das Pilhas: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+, e uv 0.6+.

Python no Shell

Buscar na documentação

Python no Shell