Ambientes Virtuais¶
Ao trabalhar em projetos Python, você provavelmente deve usar um ambiente virtual (ou um mecanismo similar) para isolar os pacotes que você instala para cada projeto.
"Informação"
Se você já sabe sobre ambientes virtuais, como criá-los e usá-los, talvez seja melhor pular esta seção. 🤓
"Dica"
Um ambiente virtual é diferente de uma variável de ambiente.
Uma variável de ambiente é uma variável no sistema que pode ser usada por programas.
Um ambiente virtual é um diretório com alguns arquivos.
"Informação"
Esta página lhe ensinará como usar ambientes virtuais e como eles funcionam.
Se você estiver pronto para adotar uma ferramenta que gerencia tudo para você (incluindo a instalação do Python), experimente uv.
Criar um Projeto¶
Primeiro, crie um diretório para seu projeto.
O que normalmente faço é criar um diretório chamado code
dentro do meu diretório home/user.
E dentro disso eu crio um diretório por projeto.
// Vá para o diretório inicial
$ cd
// Crie um diretório para todos os seus projetos de código
$ mkdir code
// Entre nesse diretório de código
$ cd code
// Crie um diretório para este projeto
$ mkdir awesome-project
// Entre no diretório do projeto
$ cd awesome-project
Crie um ambiente virtual¶
Ao começar a trabalhar em um projeto Python pela primeira vez, crie um ambiente virtual dentro do seu projeto.
"Dica"
Você só precisa fazer isso uma vez por projeto, não toda vez que trabalhar.
Para criar um ambiente virtual, você pode usar o módulo venv
que vem com o Python.
$ python -m venv .venv
O que esse comando significa
python
: usa o programa chamadopython
-m
: chama um módulo como um script, nós diremos a ele qual módulo vem em seguidavenv
: usa o módulo chamadovenv
que normalmente vem instalado com o Python.venv
: cria o ambiente virtual no novo diretório.venv
Se você tiver o uv
instalado, poderá usá-lo para criar um ambiente virtual.
$ uv venv
"Dica"
Por padrão, uv
criará um ambiente virtual em um diretório chamado .venv
.
Mas você pode personalizá-lo passando um argumento adicional com o nome do diretório.
Esse comando cria um novo ambiente virtual em um diretório chamado .venv
.
.venv
ou outro nome
Você pode criar o ambiente virtual em um diretório diferente, mas há uma convenção para chamá-lo de .venv
.
Ative o ambiente virtual¶
Ative o novo ambiente virtual para que qualquer comando Python que você executar ou pacote que você instalar o utilize.
"Dica"
Faça isso toda vez que iniciar uma nova sessão de terminal para trabalhar no projeto.
$ source .venv/bin/activate
$ .venv\Scripts\Activate.ps1
Ou se você usa o Bash para Windows (por exemplo, Git Bash):
$ source .venv/Scripts/activate
"Dica"
Toda vez que você instalar um novo pacote naquele ambiente, ative o ambiente novamente.
Isso garante que, se você usar um programa de terminal (CLI) instalado por esse pacote, você usará aquele do seu ambiente virtual e não qualquer outro que possa ser instalado globalmente, provavelmente com uma versão diferente do que você precisa.
Verifique se o ambiente virtual está ativo¶
Verifique se o ambiente virtual está ativo (o comando anterior funcionou).
"Dica"
Isso é opcional, mas é uma boa maneira de verificar se tudo está funcionando conforme o esperado e se você está usando o ambiente virtual pretendido.
$ which python
/home/user/code/awesome-project/.venv/bin/python
Se ele mostrar o binário python
em .venv/bin/python
, dentro do seu projeto (neste caso awesome-project
), então funcionou. 🎉
$ Get-Command python
C:\Users\user\code\awesome-project\.venv\Scripts\python
Se ele mostrar o binário python
em .venv\Scripts\python
, dentro do seu projeto (neste caso awesome-project
), então funcionou. 🎉
Atualizar pip
¶
"Dica"
Se você usar uv
, você o usará para instalar coisas em vez do pip
, então não precisará atualizar o pip
. 😎
Se você estiver usando pip
para instalar pacotes (ele vem por padrão com o Python), você deve atualizá-lo para a versão mais recente.
Muitos erros exóticos durante a instalação de um pacote são resolvidos apenas atualizando o pip
primeiro.
"Dica"
Normalmente, você faria isso uma vez, logo após criar o ambiente virtual.
Certifique-se de que o ambiente virtual esteja ativo (com o comando acima) e execute:
$ python -m pip install --upgrade pip
---> 100%
Adicionar .gitignore
¶
Se você estiver usando Git (você deveria), adicione um arquivo .gitignore
para excluir tudo em seu .venv
do Git.
"Dica"
Se você usou uv
para criar o ambiente virtual, ele já fez isso para você, você pode pular esta etapa. 😎
"Dica"
Faça isso uma vez, logo após criar o ambiente virtual.
$ echo "*" > .venv/.gitignore
O que esse comando significa
echo "*"
: irá "imprimir" o texto*
no terminal (a próxima parte muda isso um pouco)>
: qualquer coisa impressa no terminal pelo comando à esquerda de>
não deve ser impressa, mas sim escrita no arquivo que vai à direita de>
.gitignore
: o nome do arquivo onde o texto deve ser escrito
E *
para Git significa "tudo". Então, ele ignorará tudo no diretório .venv
.
Esse comando criará um arquivo .gitignore
com o conteúdo:
*
Instalar Pacotes¶
Após ativar o ambiente, você pode instalar pacotes nele.
"Dica"
Faça isso uma vez ao instalar ou atualizar os pacotes que seu projeto precisa.
Se precisar atualizar uma versão ou adicionar um novo pacote, você fará isso novamente.
Instalar pacotes diretamente¶
Se estiver com pressa e não quiser usar um arquivo para declarar os requisitos de pacote do seu projeto, você pode instalá-los diretamente.
"Dica"
É uma (muito) boa ideia colocar os pacotes e versões que seu programa precisa em um arquivo (por exemplo requirements.txt
ou pyproject.toml
).
$ pip install "fastapi[standard]"
---> 100%
Se você tem o uv
:
$ uv pip install "fastapi[standard]"
---> 100%
Instalar a partir de requirements.txt
¶
Se você tiver um requirements.txt
, agora poderá usá-lo para instalar seus pacotes.
$ pip install -r requirements.txt
---> 100%
Se você tem o uv
:
$ uv pip install -r requirements.txt
---> 100%
requirements.txt
Um requirements.txt
com alguns pacotes poderia se parecer com:
fastapi[standard]==0.113.0
pydantic==2.8.0
Execute seu programa¶
Depois de ativar o ambiente virtual, você pode executar seu programa, e ele usará o Python dentro do seu ambiente virtual com os pacotes que você instalou lá.
$ python main.py
Hello World
Configure seu editor¶
Você provavelmente usaria um editor. Certifique-se de configurá-lo para usar o mesmo ambiente virtual que você criou (ele provavelmente o detectará automaticamente) para que você possa obter erros de preenchimento automático e em linha.
Por exemplo:
"Dica"
Normalmente, você só precisa fazer isso uma vez, ao criar o ambiente virtual.
Desativar o ambiente virtual¶
Quando terminar de trabalhar no seu projeto, você pode desativar o ambiente virtual.
$ deactivate
Dessa forma, quando você executar python
, ele não tentará executá-lo naquele ambiente virtual com os pacotes instalados nele.
Pronto para trabalhar¶
Agora você está pronto para começar a trabalhar no seu projeto.
"Dica"
Você quer entender o que é tudo isso acima?
Continue lendo. 👇🤓
Por que ambientes virtuais¶
Para trabalhar com o FastAPI, você precisa instalar o Python.
Depois disso, você precisará instalar o FastAPI e quaisquer outros pacotes que queira usar.
Para instalar pacotes, você normalmente usaria o comando pip
que vem com o Python (ou alternativas semelhantes).
No entanto, se você usar pip
diretamente, os pacotes serão instalados no seu ambiente Python global (a instalação global do Python).
O Problema¶
Então, qual é o problema em instalar pacotes no ambiente global do Python?
Em algum momento, você provavelmente acabará escrevendo muitos programas diferentes que dependem de pacotes diferentes. E alguns desses projetos em que você trabalha dependerão de versões diferentes do mesmo pacote. 😱
Por exemplo, você pode criar um projeto chamado philosophers-stone
, este programa depende de outro pacote chamado harry
, usando a versão 1
. Então, você precisa instalar harry
.
flowchart LR
stone(philosophers-stone) -->|requires| harry-1[harry v1]
Então, em algum momento depois, você cria outro projeto chamado prisoner-of-azkaban
, e esse projeto também depende de harry
, mas esse projeto precisa do harry
versão 3
.
flowchart LR
azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]
Mas agora o problema é que, se você instalar os pacotes globalmente (no ambiente global) em vez de em um ambiente virtual local, você terá que escolher qual versão do harry
instalar.
Se você quiser executar philosophers-stone
, precisará primeiro instalar harry
versão 1
, por exemplo com:
$ pip install "harry==1"
E então você acabaria com harry
versão 1
instalado em seu ambiente Python global.
flowchart LR
subgraph global[global env]
harry-1[harry v1]
end
subgraph stone-project[philosophers-stone project]
stone(philosophers-stone) -->|requires| harry-1
end
Mas se você quiser executar prisoner-of-azkaban
, você precisará desinstalar harry
versão 1
e instalar harry
versão 3
(ou apenas instalar a versão 3
desinstalaria automaticamente a versão 1
).
$ pip install "harry==3"
E então você acabaria com harry
versão 3
instalado em seu ambiente Python global.
E se você tentar executar philosophers-stone
novamente, há uma chance de que não funcione porque ele precisa de harry
versão 1
.
flowchart LR
subgraph global[global env]
harry-1[<strike>harry v1</strike>]
style harry-1 fill:#ccc,stroke-dasharray: 5 5
harry-3[harry v3]
end
subgraph stone-project[philosophers-stone project]
stone(philosophers-stone) -.-x|⛔️| harry-1
end
subgraph azkaban-project[prisoner-of-azkaban project]
azkaban(prisoner-of-azkaban) --> |requires| harry-3
end
"Dica"
É muito comum em pacotes Python tentar ao máximo evitar alterações drásticas em novas versões, mas é melhor prevenir do que remediar e instalar versões mais recentes intencionalmente e, quando possível, executar os testes para verificar se tudo está funcionando corretamente.
Agora, imagine isso com muitos outros pacotes dos quais todos os seus projetos dependem. Isso é muito difícil de gerenciar. E você provavelmente acabaria executando alguns projetos com algumas versões incompatíveis dos pacotes, e não saberia por que algo não está funcionando.
Além disso, dependendo do seu sistema operacional (por exemplo, Linux, Windows, macOS), ele pode ter vindo com o Python já instalado. E, nesse caso, provavelmente tinha alguns pacotes pré-instalados com algumas versões específicas necessárias para o seu sistema. Se você instalar pacotes no ambiente global do Python, poderá acabar quebrando alguns dos programas que vieram com seu sistema operacional.
Onde os pacotes são instalados¶
Quando você instala o Python, ele cria alguns diretórios com alguns arquivos no seu computador.
Alguns desses diretórios são os responsáveis por ter todos os pacotes que você instala.
Quando você executa:
// Não execute isso agora, é apenas um exemplo 🤓
$ pip install "fastapi[standard]"
---> 100%
Isso fará o download de um arquivo compactado com o código FastAPI, normalmente do PyPI.
Ele também fará o download de arquivos para outros pacotes dos quais o FastAPI depende.
Em seguida, ele extrairá todos esses arquivos e os colocará em um diretório no seu computador.
Por padrão, ele colocará os arquivos baixados e extraídos no diretório que vem com a instalação do Python, que é o ambiente global.
O que são ambientes virtuais¶
A solução para os problemas de ter todos os pacotes no ambiente global é usar um ambiente virtual para cada projeto em que você trabalha.
Um ambiente virtual é um diretório, muito semelhante ao global, onde você pode instalar os pacotes para um projeto.
Dessa forma, cada projeto terá seu próprio ambiente virtual (diretório .venv
) com seus próprios pacotes.
flowchart TB
subgraph stone-project[philosophers-stone project]
stone(philosophers-stone) --->|requires| harry-1
subgraph venv1[.venv]
harry-1[harry v1]
end
end
subgraph azkaban-project[prisoner-of-azkaban project]
azkaban(prisoner-of-azkaban) --->|requires| harry-3
subgraph venv2[.venv]
harry-3[harry v3]
end
end
stone-project ~~~ azkaban-project
O que significa ativar um ambiente virtual¶
Quando você ativa um ambiente virtual, por exemplo com:
$ source .venv/bin/activate
$ .venv\Scripts\Activate.ps1
Ou se você usa o Bash para Windows (por exemplo, Git Bash):
$ source .venv/Scripts/activate
Esse comando criará ou modificará algumas variáveis de ambiente que estarão disponíveis para os próximos comandos.
Uma dessas variáveis é a variável PATH
.
"Dica"
Você pode aprender mais sobre a variável de ambiente PATH
na seção Variáveis de ambiente.
A ativação de um ambiente virtual adiciona seu caminho .venv/bin
(no Linux e macOS) ou .venv\Scripts
(no Windows) à variável de ambiente PATH
.
Digamos que antes de ativar o ambiente, a variável PATH
estava assim:
/usr/bin:/bin:/usr/sbin:/sbin
Isso significa que o sistema procuraria programas em:
/usr/bin
/bin
/usr/sbin
/sbin
C:\Windows\System32
Isso significa que o sistema procuraria programas em:
C:\Windows\System32
Após ativar o ambiente virtual, a variável PATH
ficaria mais ou menos assim:
/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin
Isso significa que o sistema agora começará a procurar primeiro por programas em:
/home/user/code/awesome-project/.venv/bin
antes de procurar nos outros diretórios.
Então, quando você digita python
no terminal, o sistema encontrará o programa Python em
/home/user/code/awesome-project/.venv/bin/python
e usa esse.
C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32
Isso significa que o sistema agora começará a procurar primeiro por programas em:
C:\Users\user\code\awesome-project\.venv\Scripts
antes de procurar nos outros diretórios.
Então, quando você digita python
no terminal, o sistema encontrará o programa Python em
C:\Users\user\code\awesome-project\.venv\Scripts\python
e usa esse.
Um detalhe importante é que ele colocará o caminho do ambiente virtual no início da variável PATH
. O sistema o encontrará antes de encontrar qualquer outro Python disponível. Dessa forma, quando você executar python
, ele usará o Python do ambiente virtual em vez de qualquer outro python
(por exemplo, um python
de um ambiente global).
Ativar um ambiente virtual também muda algumas outras coisas, mas esta é uma das mais importantes.
Verificando um ambiente virtual¶
Ao verificar se um ambiente virtual está ativo, por exemplo com:
$ which python
/home/user/code/awesome-project/.venv/bin/python
$ Get-Command python
C:\Users\user\code\awesome-project\.venv\Scripts\python
Isso significa que o programa python
que será usado é aquele no ambiente virtual.
você usa which
no Linux e macOS e Get-Command
no Windows PowerShell.
A maneira como esse comando funciona é que ele vai e verifica na variável de ambiente PATH
, passando por cada caminho em ordem, procurando pelo programa chamado python
. Uma vez que ele o encontre, ele mostrará o caminho para esse programa.
A parte mais importante é que quando você chama `python
, esse é exatamente o "python
" que será executado.
Assim, você pode confirmar se está no ambiente virtual correto.
"Dica"
É fácil ativar um ambiente virtual, obter um Python e então ir para outro projeto.
E o segundo projeto não funcionaria porque você está usando o Python incorreto, de um ambiente virtual para outro projeto.
É útil poder verificar qual python
está sendo usado. 🤓
Por que desativar um ambiente virtual¶
Por exemplo, você pode estar trabalhando em um projeto philosophers-stone
, ativar esse ambiente virtual, instalar pacotes e trabalhar com esse ambiente.
E então você quer trabalhar em outro projeto prisoner-of-azkaban
.
Você vai para aquele projeto:
$ cd ~/code/prisoner-of-azkaban
Se você não desativar o ambiente virtual para philosophers-stone
, quando você executar python
no terminal, ele tentará usar o Python de philosophers-stone
.
$ cd ~/code/prisoner-of-azkaban
$ python main.py
// Erro ao importar o Sirius, ele não está instalado 😱
Traceback (most recent call last):
File "main.py", line 1, in <module>
import sirius
Mas se você desativar o ambiente virtual e ativar o novo para prisoner-of-askaban
, quando você executar python
, ele usará o Python do ambiente virtual em prisoner-of-azkaban
.
$ cd ~/code/prisoner-of-azkaban
// Você não precisa estar no diretório antigo para desativar, você pode fazer isso de onde estiver, mesmo depois de ir para o outro projeto 😎
$ deactivate
// Ative o ambiente virtual em prisoner-of-azkaban/.venv 🚀
$ source .venv/bin/activate
// Agora, quando você executar o python, ele encontrará o pacote sirius instalado neste ambiente virtual ✨
$ python main.py
Eu juro solenemente 🐺
Alternativas¶
Este é um guia simples para você começar e lhe ensinar como tudo funciona por baixo.
Existem muitas alternativas para gerenciar ambientes virtuais, dependências de pacotes (requisitos) e projetos.
Quando estiver pronto e quiser usar uma ferramenta para gerenciar todo o projeto, dependências de pacotes, ambientes virtuais, etc., sugiro que você experimente o uv.
uv
pode fazer muitas coisas, ele pode:
- Instalar o Python para você, incluindo versões diferentes
- Gerenciar o ambiente virtual para seus projetos
- Instalar pacotes
- Gerenciar dependências e versões de pacotes para seu projeto
- Certifique-se de ter um conjunto exato de pacotes e versões para instalar, incluindo suas dependências, para que você possa ter certeza de que pode executar seu projeto em produção exatamente da mesma forma que em seu computador durante o desenvolvimento, isso é chamado de bloqueio
- E muitas outras coisas
Conclusão¶
Se você leu e entendeu tudo isso, agora você sabe muito mais sobre ambientes virtuais do que muitos desenvolvedores por aí. 🤓
Saber esses detalhes provavelmente será útil no futuro, quando você estiver depurando algo que parece complexo, mas você saberá como tudo funciona. 😎