Python venv

Na aula pip: Instalando Pacotes, o Ubuntu recusou o pip install e sugeriu "crie um ambiente virtual". Lá você usou três comandos sem muita explicação. Nesta aula você vai entender o que é esse ambiente virtual (em inglês, virtual environment, abreviado venv), o que tem dentro dele, como ligar e desligar, e por que todo projeto Python sério tem o seu.

A ideia: uma caixa de ferramentas para cada trabalho

A Ana faz bolos para fora e também conserta bicicletas no fim de semana. Ela não guarda as formas de bolo junto com as chaves de boca: cada atividade tem a sua caixa, com as ferramentas certas. Se um dia ela trocar a batedeira, a caixa da bicicleta nem fica sabendo.

Com os programas Python é igual. A lojinha da Ana usa o requests na versão mais nova; a agenda, que ela escreveu no ano passado, só funciona com uma versão mais antiga. Se os dois projetos usassem o mesmo Python, com os mesmos pacotes, um deles ia quebrar. A solução é dar a cada projeto a sua caixa:

Um ambiente virtual é só isso: uma pasta com um Python "particular" e um lugar para os pacotes daquele projeto. Nada é instalado no sistema, e apagar a pasta desfaz tudo.

1. Criando: python3 -m venv .venv

A Ana vai começar um projeto novo, as encomendas da padaria. Primeiro a pasta do projeto, depois o ambiente dentro dela:

$ mkdir padaria
$ cd padaria
$ python3 -m venv .venv
$ ls -a
.
..
.venv

python3

O Python que vai servir de base para o ambiente (o do sistema, o 3.14).

-m venv

"Rode o módulo venv": ele vem com o Python e sabe criar ambientes.

.venv

O nome da pasta do ambiente. Pode ser qualquer nome, mas .venv é o costume: os editores de código (como o VS Code) procuram por ele, e o ponto na frente deixa a pasta "escondida" no ls comum (por isso o -a, de "all", "todos").

O comando não imprime nada: no terminal, silêncio quer dizer que deu certo. Leva um ou dois segundos, porque ele também instala um pip novinho lá dentro.

O que tem dentro da .venv

$ ls -a .venv
.
..
.gitignore
bin
include
lib
lib64
pyvenv.cfg

$ cat .venv/pyvenv.cfg
home = /usr/bin
include-system-site-packages = false
version = 3.14.4
executable = /usr/bin/python3.14
command = /usr/bin/python3 -m venv /home/ana/padaria/.venv
$ cat .venv/.gitignore
# Created by venv; see https://docs.python.org/3/library/venv.html
*

home = /usr/bin

A pasta do Python original.

include-system-site-packages = false

"Incluir os pacotes do sistema? Não." O ambiente começa limpo e não enxerga os pacotes instalados pelo apt.

version = 3.14.4

A versão do Python do ambiente.

command = …

O comando que criou o ambiente, com o caminho completo da pasta. Guarde isso: o ambiente sabe onde foi criado.

*

No .gitignore, o asterisco quer dizer "ignore tudo nesta pasta".

E a pasta bin:

$ ls -l .venv/bin
total 36
-rw-r--r-- 1 ana ana 9031 Oct 18 11:48 Activate.ps1
-rw-r--r-- 1 ana ana 2158 Oct 18 11:48 activate
-rw-r--r-- 1 ana ana  914 Oct 18 11:48 activate.csh
-rw-r--r-- 1 ana ana 2185 Oct 18 11:48 activate.fish
-rwxrwxr-x 1 ana ana  240 Oct 18 11:48 pip
-rwxrwxr-x 1 ana ana  240 Oct 18 11:48 pip3
-rwxrwxr-x 1 ana ana  240 Oct 18 11:48 pip3.14
lrwxrwxrwx 1 ana ana    7 Oct 18 11:48 python -> python3
lrwxrwxrwx 1 ana ana   16 Oct 18 11:48 python3 -> /usr/bin/python3
lrwxrwxrwx 1 ana ana    7 Oct 18 11:48 python3.14 -> python3
lrwxrwxrwx 1 ana ana    7 Oct 18 11:48 𝜋thon -> python3

activate

O script que liga o ambiente no bash (o terminal do Ubuntu). Os outros (.csh, .fish, .ps1) são para outros terminais, como o PowerShell do Windows.

pip, pip3, pip3.14

Três nomes para o mesmo pip, o do ambiente.

python3 -> /usr/bin/python3

A seta indica um atalho (link simbólico): o Python do ambiente não é uma cópia inteira, é um atalho para o Python do sistema. O que muda é onde ele procura os pacotes.

python -> python3

Dentro do ambiente existe o comando python, sem o 3. Fora dele, no Ubuntu, não existe.

𝜋thon

Uma brincadeira do Python 3.14 (o "pi" de 3,14…): mais um atalho, com a letra grega π. Funciona, mas ninguém usa no dia a dia.

2. Ativando: source .venv/bin/activate

Criar o ambiente não basta: o terminal continua usando o Python do sistema. Veja:

$ which python3
/usr/bin/python3
$ python3 -c "import sys; print(sys.prefix)"
/usr

which ("qual") mostra qual programa roda quando você digita um nome. E sys.prefix é a pasta "de casa" do Python que está rodando (o módulo sys tem aula própria: Os Módulos os e sys). Os dois apontam para o sistema. Agora a Ana ativa o ambiente:

$ source .venv/bin/activate
(.venv) ana@notebook:~/padaria$ which python3
/home/ana/padaria/.venv/bin/python3
(.venv) ana@notebook:~/padaria$ which python
/home/ana/padaria/.venv/bin/python
(.venv) ana@notebook:~/padaria$ python -c "import sys; print(sys.prefix)"
/home/ana/padaria/.venv
(.venv) ana@notebook:~/padaria$ pip list
Package Version
------- -------
pip     25.1.1

source

"Leia e execute este arquivo aqui, neste terminal". É obrigatório: o activate muda o terminal em que você está, e só o source deixa ele fazer isso.

.venv/bin/activate

O caminho do script, a partir da pasta do projeto.

(.venv)

O prompt ganhou o nome do ambiente na frente. É o sinal de que ele está ativo: olhe para ele sempre antes de rodar pip install.

which python3

Agora aponta para dentro da .venv.

pip list

Só o pip: o ambiente é novo e limpo.

O que o activate fez, por baixo, foi pôr a pasta .venv/bin na frente da lista de lugares onde o terminal procura os programas. Por isso python e pip agora são os do ambiente. Ele também criou a variável VIRTUAL_ENV, com o caminho do ambiente ativo (echo $VIRTUAL_ENV mostra).

3. O próprio programa sabe se está num ambiente

Um programa Python consegue descobrir qual Python o está rodando. sys.executable é o caminho do Python em uso; sys.base_prefix é a pasta do Python original. Num ambiente virtual, sys.prefix (a pasta do ambiente) é diferente de sys.base_prefix:

import sys

print("Python em uso:", sys.executable)
print("Ambiente virtual?", sys.prefix != sys.base_prefix)

$ python3 onde.py
Python em uso: /usr/bin/python3
Ambiente virtual? False
$ source .venv/bin/activate
(.venv) ana@notebook:~/padaria$ python onde.py
Python em uso: /home/ana/padaria/.venv/bin/python
Ambiente virtual? True

O mesmo arquivo, dois resultados: o que muda é qual Python roda o programa.

Usar o ambiente sem ativar

Ativar é uma comodidade. Dá para chamar o Python do ambiente direto, pelo caminho, sem source nenhum. O resultado é o mesmo:

$ .venv/bin/python onde.py
Python em uso: /home/ana/padaria/.venv/bin/python
Ambiente virtual? True

É assim que se roda um programa de um projeto a partir de outro script ou de um agendador, onde ninguém vai digitar source. O mesmo vale para o pip: .venv/bin/pip install requests instala no ambiente, ativo ou não. E por que o .venv/bin/pip sabe para qual Python instalar? Porque a primeira linha dele diz:

$ cat .venv/bin/pip
#!/home/ana/padaria/.venv/bin/python3
# -*- coding: utf-8 -*-
import re
import sys
from pip._internal.cli.main import main
if __name__ == '__main__':
    sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0])
    sys.exit(main())

O pip é um programinha Python, e a linha #! do começo (o "shebang") diz qual Python roda ele: o da .venv da padaria, com o caminho completo. Isso vai ser importante no Quando dá errado.

with open("pyvenv.cfg", encoding="utf-8") as arquivo:
    for linha in arquivo:
        linha = linha.strip()
        print(linha)

home = /usr/bin
include-system-site-packages = false
version = 3.14.4
executable = /usr/bin/python3.14
command = /usr/bin/python3 -m venv /home/ana/padaria/.venv

with open("pyvenv.cfg", encoding="utf-8") as arquivo:
    for linha in arquivo:
        linha = linha.strip()
        chave, valor = linha.split(" = ")
        if chave == "version":
            print(f"Este ambiente usa o Python {valor}")

4. Desativando: deactivate

Terminou o trabalho no projeto? deactivate ("desativar") devolve o terminal ao normal. O (.venv) some do prompt, e o python sem 3 volta a não existir:

$ source .venv/bin/activate
(.venv) ana@notebook:~/padaria$ deactivate
$ which python
$ python --version
Comando 'python' não encontrado, você quis dizer:
  comando 'python3' do deb python3
  comando 'python' do deb python-is-python3

O which python não respondeu nada: não há programa com esse nome fora do ambiente. Desativar não apaga nada; o ambiente continua lá, com os pacotes, esperando o próximo source.

5. Cada projeto com o seu

Agora o exemplo da introdução, de verdade. A agenda da Ana precisa do requests 2.32.3. Ela cria o ambiente da agenda com a opção --prompt, que troca o nome que aparece no prompt:

$ mkdir agenda
$ cd agenda
$ python3 -m venv .venv --prompt agenda
$ source .venv/bin/activate
(agenda) ana@notebook:~/agenda$ pip install -q "requests==2.32.3"
(agenda) ana@notebook:~/agenda$ pip list
Package            Version
------------------ ---------
certifi            2026.7.22
charset-normalizer 3.5.2
idna               3.20
pip                25.1.1
requests           2.32.3
urllib3            2.8.0
(agenda) ana@notebook:~/agenda$ deactivate

(O -q, de quiet, "quieto", faz o pip instalar sem imprimir o andamento.) E a lojinha, da aula do pip, continua com a versão dela:

$ cd ../loja
$ source .venv/bin/activate
(.venv) ana@notebook:~/loja$ pip list
Package            Version
------------------ ---------
certifi            2026.7.22
charset-normalizer 3.5.2
idna               3.20
pip                25.1.1
requests           2.34.2
urllib3            2.8.0
(.venv) ana@notebook:~/loja$ deactivate

Duas versões do mesmo pacote no mesmo computador, cada uma na sua caixa, sem uma atrapalhar a outra.

6. Apagar e recriar: o ambiente é descartável

Um ambiente virtual não guarda nada que você escreveu: o seu código fica fora dele, na pasta do projeto. Por isso ele é descartável. Estragou, ficou com pacotes demais, mudou de versão do Python? Apague e crie de novo. O requirements.txt (aula pip) traz os pacotes de volta:

$ cd loja
$ ls
baixar.py
requirements.txt
$ rm -rf .venv
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) ana@notebook:~/loja$ pip install -q -r requirements.txt
(.venv) ana@notebook:~/loja$ pip list
Package            Version
------------------ ---------
certifi            2026.7.22
charset-normalizer 3.5.2
idna               3.20
pip                25.1.1
requests           2.34.2
urllib3            2.8.0
(.venv) ana@notebook:~/loja$ echo $VIRTUAL_ENV
/home/ana/loja/.venv
(.venv) ana@notebook:~/loja$ python baixar.py
Código: 200
Tipo: text/html; charset=utf-8
Tamanho: 577 caracteres

(O ls não mostra a .venv porque o nome começa com ponto.) Os mesmos pacotes, nas mesmas versões, e o programa funcionando. Essa é a rotina de quem recebe um projeto Python de outra pessoa: criar o ambiente, ativar, pip install -r requirements.txt.

Formas diferentes de usar o ambiente

Quando dá errado

$ .venv/bin/activate
bash: .venv/bin/activate: Permissão negada

$ source venv/bin/activate
bash: venv/bin/activate: Arquivo ou diretório inexistente

$ deactivate
deactivate: comando não encontrado

$ python3 -m venv
usage: python3 -m venv [-h] [--system-site-packages] [--symlinks | --copies]
                       [--clear] [--upgrade] [--without-pip] [--prompt PROMPT]
                       [--upgrade-deps] [--without-scm-ignore-files]
                       ENV_DIR [ENV_DIR ...]
python3 -m venv: error: the following arguments are required: ENV_DIR

$ cp -r loja loja-copia
$ cd loja-copia
$ source .venv/bin/activate
(.venv) ana@notebook:~/loja-copia$ which python
/home/ana/loja/.venv/bin/python
(.venv) ana@notebook:~/loja-copia$ pip --version
pip 25.1.1 from /home/ana/loja/.venv/lib/python3.14/site-packages/pip (python 3.14)

$ grep -n "export VIRTUAL_ENV=" .venv/bin/activate
49:        export VIRTUAL_ENV=/home/ana/loja/.venv

Para fechar, uma comparação que o próprio pip não faz por você: o que muda entre os ambientes de dois projetos.

loja = {"certifi": "2026.7.22", "idna": "3.20", "requests": "2.34.2", "urllib3": "2.8.0"}
agenda = {"certifi": "2026.7.22", "idna": "3.20", "requests": "2.32.3", "urllib3": "2.8.0"}

for pacote in loja:
    print(pacote)

loja = {"certifi": "2026.7.22", "idna": "3.20", "requests": "2.34.2", "urllib3": "2.8.0"}
agenda = {"certifi": "2026.7.22", "idna": "3.20", "requests": "2.32.3", "urllib3": "2.8.0"}

for pacote in loja:
    if loja[pacote] != agenda[pacote]:
        print(f"{pacote}: loja {loja[pacote]}, agenda {agenda[pacote]}")

Referência rápida

Exercícios

Missão final: o ambiente está ativo?

def prompt(pasta, ambiente):
    base = f"ana@notebook:{pasta}$"
    return base


print("Com ambiente:", prompt("~/loja", ".venv"))
print("Sem ambiente:", prompt("~/agenda", None))

def prompt(pasta, ambiente):
    base = f"ana@notebook:{pasta}$"
    if ambiente is None:
        return base
    return f"({ambiente}) {base}"


print("Com ambiente:", prompt("~/loja", ".venv"))
print("Sem ambiente:", prompt("~/agenda", None))

Resumo

• Um ambiente virtual é uma pasta (o costume é .venv) com um Python particular e os pacotes de um projeto.
• Crie com python3 -m venv .venv, ative com source .venv/bin/activate, desative com deactivate.
• Ativo, o prompt começa com (.venv), e python e pip são os do ambiente (which python confirma). Vale só para aquele terminal.
• Sem ativar, chame pelo caminho: .venv/bin/python programa.py.
• Cada projeto com o seu: dois projetos podem usar versões diferentes do mesmo pacote no mesmo computador.
• O ambiente é descartável e preso ao lugar onde foi criado: não copie nem mova; apague e recrie com pip install -r requirements.txt.