Python e Virtualenv: Como Programar em Ambientes Virtuais

✅ Artigo atualizado em Setembro 2026: o passo a passo agora usa o venv, que já vem com o Python 3, com ativação no Linux, macOS e Windows, pip install e requirements.txt. O virtualenv continua como alternativa, e o uv aparece como opção moderna. Removemos as instruções de Python 2 e de sudo pip.

Olá pessoal! Nesse post, vamos entender como funcionam os ambientes virtuais do Python: o módulo venv, que já vem com o Python 3, e o incrível virtualenv, a ferramenta que deu origem a ele. Os dois permitem criar ambientes isolados de desenvolvimento Python.

Dessa forma é possível a utilização de diversas bibliotecas, em versões diferentes, em projetos diferentes, sem que haja conflitos entre elas.

Neste post vamos aprender:

• As vantagens ao se isolar seu ambiente de desenvolvimento Python
• Como criar, ativar e desativar um ambiente com o venv nativo (Linux, macOS e Windows)
• Como instalar pacotes e guardar as dependências no requirements.txt
• Quando escolher o virtualenv (ou o uv) e como usar versões diferentes do Python no mesmo PC!

Portanto, se você está cansado de misturar pacotes Python ou ver aquele incômodo erro ModuleNotFoundError: No module named 'foo', vamos nessa!

Vá Direto ao Assunto…

• Introdução
• Primeiros Passos
• Opção --python
• Outras Opções Interessantes
• Arquivo de Configuração virtualenv.ini
• Alternativa Moderna: uv
• Conclusão

Introdução

Quando desenvolvemos em Python, é comum ficarmos maravilhados com o poder de suas bibliotecas.

Tudo se torna mais fácil ainda quando podemos baixá-las com um simples comando (pip install <pacote> por exemplo).

Dessa forma, se não tomarmos alguns cuidados, podemos deixar nosso ambiente de desenvolvimento lotado de bibliotecas.

Isso quando não as utilizamos algumas vezes e depois nunca mais.

Não apenas isso! Imagine o seguinte cenário: você está desenvolvendo uma aplicação, chamada CoolApp que utiliza a biblioteca powerlib em sua versão 1.0.

Por enquanto tudo ok…

Daí, algum tempo se passa e você acaba largando essa aplicação, pois cansou-se dela e ela nem era tão promissora assim.

Você começa então a desenvolver uma aplicação ultra mega powerfull, chamada TheApp, que por coincidência utiliza a mesma biblioteca (powerlib), mas em sua versão 2.0.

Bom, você inocentemente realiza o upgrade dessa biblioteca no Python do sistema (algo como sudo pip install --upgrade powerlib) para sua versão 2.0 para poder continuar seu desenvolvimento.

Então me diga: o que acontecerá caso você tente retomar o desenvolvimento da aplicação CoolApp (juntamente com o desenvolvimento da aplicação TheApp)?

Resposta: Caso você tenha instalado todas as suas bibliotecas no diretório global do sistema (algo como /usr/lib/pythonX.Y/site-packages), apenas uma aplicação irá funcionar… NOOOOOOOOOOOO!!!!

Ou seja, quando desenvolvemos Python “globalmente” e não isolamos cada ambiente de desenvolvimento, podemos ter conflitos entre versões de bibliotecas.

Não use sudo pip. Instalar pacotes com sudo no Python do sistema pode quebrar ferramentas do próprio sistema operacional. Tanto que distribuições Linux recentes (como Debian 12 e Ubuntu 23.04 em diante) bloqueiam o pip install global com o erro externally-managed-environment e pedem justamente que você use um ambiente virtual.

Outro ponto, e se quisermos desenvolver um projeto em Python 3.12 e outro em Python 3.13? Como fazer?

E ainda mais: e se você não puder instalar suas dependências no diretório global site-packages (seu programa pode estar sendo executado em um host remoto, sem permissão de administrador, por exemplo)?

Mas calma, a solução para todos os seus problemas está aqui, e chama-se ambiente virtual. Hoje o Python já traz o módulo venv para isso (desde o Python 3.3, que incorporou à biblioteca padrão um subconjunto do virtualenv). O virtualenv continua existindo como ferramenta externa, com alguns recursos a mais. Portanto, vamos começar entendendo melhor do que se trata!

Como o Virtualenv Funciona

O funcionamento do virtualenv (e do venv) é realmente simples. Ele cria uma pasta com o mínimo necessário para “redirecionar” o Python para um ambiente próprio:

• Um executável do Python (um link ou cópia do Python que você usou para criar o ambiente);
• O gerenciador de pacotes pip;
• Um diretório site-packages próprio, vazio no início, onde ficarão as dependências do projeto;
• Scripts de ativação (activate) para os terminais mais comuns;
• Um arquivo pyvenv.cfg, que aponta para a instalação base do Python.

As bibliotecas comuns do Python (standard library) não são copiadas: o ambiente continua usando as da instalação base, por isso criar um ambiente é rápido e ocupa pouco espaço. E o seu código fonte fica fora da pasta do ambiente, na pasta do projeto.

Assim, ao instalar uma nova dependência dentro do ambiente virtual, ela será colocada no diretório site-packages relativo à esse ambiente, e não mais globalmente.

Assim, só esse ambiente enxergará essa dependência. Show, né?!

Primeiros Passos

Instalação

O venv já vem com o Python 3, então na maioria dos casos não há nada para instalar. O pip também já vem junto com o Python (desde a versão 3.4).

Em algumas distribuições Linux baseadas em Debian/Ubuntu, o venv fica em um pacote separado. Se o comando da próxima seção reclamar que o venv/ensurepip não está disponível, instale-o com:

1

$ sudo apt install python3-venv

Se preferir o virtualenv (as vantagens dele aparecem mais abaixo, na seção sobre a opção --python), a documentação oficial recomenda instalá-lo como ferramenta isolada, e não no Python do sistema. Use uma das opções abaixo:

1
2
3

$ uv tool install virtualenv
$ pipx install virtualenv
$ python3 -m pip install --user virtualenv

Pronto! Agora vamos começar a criar nossos ambientes!

Inicializando um Ambiente Virtual

Com o venv, basta um comando dentro da pasta do seu projeto. Olha que simples:

1

$ python3 -m venv .venv

No Windows, o comando é o mesmo, trocando python3 por python (ou pelo lançador py):

1

C:\meu_projeto> python -m venv .venv

Esse comando cria um novo ambiente de desenvolvimento totalmente isolado na pasta .venv, que é o nome mais usado por convenção.

Com o virtualenv, a ideia é a mesma: virtualenv [opções] <nome_da_pasta>.

1

$ virtualenv .venv

Nessa pasta são criados alguns diretórios importantes, como:

• .venv/lib (no Windows, .venv\Lib): contém o site-packages do ambiente. Os pacotes baixados via pip serão instalados em .venv/lib/pythonX.Y/site-packages/ (não mais globalmente).
• .venv/bin (no Windows, .venv\Scripts): residem o executável do Python do ambiente, o pip e os scripts de ativação. Com o ambiente ativado, os comandos python script.py e .venv/bin/python script.py produzem exatamente o mesmo resultado.
• .venv/pyvenv.cfg: diz ao Python qual é a instalação base usada pelo ambiente.

Script de Ativação do Ambiente Virtual

Após criar o seu novo ambiente, podemos ativá-lo. No Linux e macOS (bash/zsh):

1

$ source .venv/bin/activate

O comando source lê um arquivo e executa os comandos contidos ali.

No Windows, o comando depende do terminal:

1
2
3
4
5

REM Prompt de Comando (cmd.exe)
C:\meu_projeto> .venv\Scripts\activate.bat

# PowerShell
PS C:\meu_projeto> .venv\Scripts\Activate.ps1

Se o PowerShell bloquear a execução do script, libere scripts locais para o seu usuário com Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser.

Ao ativar o ambiente, o diretório .venv/bin (ou .venv\Scripts) será adicionado como primeiro registro do caminho PATH do seu sistema operacional.

Ele também altera o padrão do seu prompt, adicionando o prefixo (.venv) para indicar que você está em um ambiente virtual.

Organizar ambientes virtuais é só o começo: para aprender Python de verdade, do básico ao Django, com prática guiada, dá uma olhada na Jornada Python:

Domine Python: A Linguagem da Inteligência Artificial, do Desenvolvimento Web e das Carreiras do Futuro.

A mais completa formação para você se tornar um especialista em Python, pronto para construir desde aplicações web robustas com Django até projetos de Inteligência Artificial e Ciência de Dados .

Quero conhecer!

Nota 4,9 de 5 na Hotmart O curso de Python mais bem avaliado da Hotmart!

Instalando Pacotes e o requirements.txt

Com o ambiente ativado, o pip instala tudo dentro do .venv, sem sudo:

1

(.venv) $ python -m pip install requests

Para registrar as dependências do projeto (e conseguir recriar o ambiente em outra máquina), salve a lista de pacotes instalados em um requirements.txt:

1

(.venv) $ python -m pip freeze > requirements.txt

O arquivo gerado fica parecido com isto (as versões dependem do dia em que você instalar):

1
2
3
4
5

certifi==2026.7.22
charset-normalizer==3.5.1
idna==3.20
requests==2.34.2
urllib3==2.8.0

Em outra máquina (ou num ambiente novo), basta criar e ativar um ambiente e rodar:

1

(.venv) $ python -m pip install -r requirements.txt

Versione o requirements.txt no Git, mas não a pasta .venv: ela deve ser descartável e recriada quando preciso. Adicione .venv/ ao seu .gitignore.

Como Desativar seu Ambiente Virtual

Para desativar o ambiente virtual e voltar ao Python do sistema, basta executar (o comando é o mesmo no Linux, macOS e Windows):

1

$ deactivate

Desativar não apaga nada: o ambiente continua na pasta .venv, pronto para ser ativado de novo. Se você quiser remover o ambiente de vez (por exemplo, para recriá-lo a partir do requirements.txt), apague a pasta:

1

$ rm -r .venv

Fazendo isso, seu ambiente virtual é desfeito e tudo que foi instalado nele é apagado (comando rm; no Windows, apague a pasta .venv pelo Explorer ou com rmdir /s /q .venv no cmd).

Estou desenvolvendo o Ebookr.ai, uma plataforma que transforma suas ideias em ebooks profissionais usando IA - com geração de capa, infográficos e exportação em PDF. Te convido a conhecer!

Opção --python

Um ambiente virtual usa sempre uma versão específica do Python, e essa versão precisa estar instalada na sua máquina.

Com o venv, o ambiente usa o Python que executou o comando. Então, para criar um ambiente com o Python 3.12, chame o venv a partir dele:

1
2
3
4
5

# Linux e macOS
$ python3.12 -m venv .venv

# Windows (lançador py)
C:\meu_projeto> py -3.12 -m venv .venv

Já o virtualenv tem a opção --python (ou -p), que procura a versão desejada no sistema para você. Ela aceita a versão, o nome do executável ou o caminho completo do binário:

1
2
3

$ virtualenv --python=3.12 .venv
$ virtualenv --python=python3.13 .venv
$ virtualenv --python=/usr/local/bin/python3 .venv

Caso você não saiba o caminho do binário do Python que você está procurando, utilize o comando which (no Windows, where). Por exemplo, which python3 pode responder com /usr/local/bin/python3.

Com seu ambiente ativado, verifique qual versão está sendo utilizada, com o comando python --version.

Pronto! Várias versões do Python no mesmo sistema operacional de maneira simples!

Esse é um dos motivos para escolher o virtualenv no lugar do venv. Segundo a documentação oficial, ele também é mais rápido para criar ambientes (usa cache), pode ser atualizado pelo pip independentemente do Python e tem um sistema de plugins. Para a maioria dos projetos, porém, o venv nativo resolve.

Outras Opções Interessantes

De acordo com sua documentação, o comando do virtualenv possui algumas opções e é utilizado da seguinte maneira: virtualenv [opções] <nome_da_pasta>.

Para a lista completa de valores possíveis de [opções], acesse sua documentação ou rode virtualenv --help.

Separei algumas opções interessantes para vocês:

• --system-site-packages: Essa opção cria um ambiente que também enxerga as dependências já instaladas globalmente. Ou seja, não será um ambiente limpo (o venv tem a mesma opção).
• --python=VERSAO_OU_CAMINHO (ou -p): Usado para definir a versão do Python que será utilizada nesse ambiente virtual.
• --no-pip: Cria o ambiente sem o pip (no venv, o equivalente é --without-pip).
• --no-setuptools: Cria o ambiente sem o setuptools.

Está curtindo esse conteúdo?

Que tal receber 30 dias de conteúdo direto na sua Caixa de Entrada?

Sua assinatura não pôde ser validada.

Você fez sua assinatura com sucesso.

Assine as PyDicas e receba 30 dias do melhor conteúdo Python na sua Caixa de Entrada: direto e sem enrolação!

Seu nome

Seu e-mail

ASSINAR PYDICAS

Arquivo de Configuração virtualenv.ini

Este recurso é exclusivo do virtualenv (o venv não tem arquivo de configuração).

Ao criar um novo ambiente, o virtualenv busca parâmetros no arquivo virtualenv.ini, que fica na pasta de configuração do usuário. No Linux, o padrão é ~/.config/virtualenv/virtualenv.ini. O caminho exato do seu sistema (Linux, macOS ou Windows) aparece no final da saída de virtualenv --help, e você pode apontar para outro arquivo com a variável de ambiente VIRTUALENV_CONFIG_FILE.

Nesse arquivo, podemos adicionar parâmetros do virtualenv que serão utilizados em todos os ambientes criados. O nome de cada chave é o nome da opção sem os -- iniciais e com _ no lugar de - (por exemplo, --no-pip vira no_pip).

Por exemplo, podemos definir opções da seguinte forma:

1
2
3
4

[virtualenv]
no_pip = true
system_site_packages = true
python = /opt/python-3.14/bin/python

Assim, todo ambiente que criarmos terão essas opções por padrão (sem termos que digitar os parâmetros toda vez).

Alternativa Moderna: uv

Se você quer algo ainda mais rápido, vale conhecer o uv, da Astral. Segundo a documentação oficial, ele é “um gerenciador de pacotes e projetos Python extremamente rápido, escrito em Rust”, de 10 a 100 vezes mais rápido que o pip. Ele também consegue baixar e instalar versões do Python para você.

Para instalar (Linux e macOS):

1

$ curl -LsSf https://astral.sh/uv/install.sh | sh

No Windows (PowerShell):

1

PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

O fluxo com ambientes virtuais fica muito parecido com o que vimos:

1
2
3
4
5

$ uv venv                    # cria o ambiente em .venv
$ uv venv --python 3.12      # ou com uma versão específica do Python
$ source .venv/bin/activate  # no Windows: .venv\Scripts\activate
$ uv pip install requests
$ uv pip install -r requirements.txt

O uv é uma ferramenta externa e mais recente; o venv continua sendo a opção que funciona em qualquer instalação do Python, sem instalar nada.

Conclusão

O uso de ambientes virtuais traz muitas vantagens e facilidades quando desenvolvemos em Python, principalmente na separação de ambientes de desenvolvimento.

Também nos ajuda muito na solução de conflitos entre versões de uma biblioteca e é essencial para o desenvolvimento de aplicações utilizando diferentes versões do Python em uma mesma máquina (sem ter que recorrer à máquinas virtuais, por exemplo)

Para começar, o venv nativo resolve a maioria dos casos: python3 -m venv .venv, ativar, pip install e requirements.txt. Se precisar de mais velocidade ou de alternar entre várias versões do Python com facilidade, o virtualenv e o uv são ótimas opções.

Caso você ainda não utilize ambientes virtuais, eu aconselho a começar o mais rápido possível e aproveitar ao máximo essas ferramentas poderosas e extremamente simples que eu acabei de apresentar a vocês.

Com o ambiente virtual pronto, um ótimo próximo passo é criar seu primeiro projeto Django em 15 minutos e depois seguir o guia completo de Django. Se ainda não tem o Python instalado, veja como instalar o Python no Linux.

Depois de organizar seu ambiente, aproveite para praticar de verdade: a Jornada Python, nosso curso completo de Python te leva do básico até projetos reais com Django.

Bom… Espero que tenham gostado! E se você achou interessante este post, e acha que ele facilitou a sua vida organizando seu ambiente Python, não se esqueça de deixar aqui seu comentário ou sugestão!

Assim como você, eles são sempre bem vindos!

Até a próxima!

Por Vinícius Ramos em 05/04/2018

Engenheiro de Computação pela UnB com especialização em Inteligência Artificial. Sr. Software Engineer com 10+ anos de experiência desenvolvendo sistemas críticos em Python e Django. Atuei no Banco do Brasil liderando equipes para monitoramento de mainframe, trabalhei como desenvolvedor sênior em projetos forenses para a Polícia Federal, e atualmente sou engenheiro de software na Labcorp (Estados Unidos), desenvolvendo soluções escaláveis para testes genéticos. Fundador da Python Academy, compartilhando conhecimento técnico com a comunidade brasileira desde 2018.

Bora se conectar no LinkedIn! vinicius-aramos

Minhas redes:

• 
• 
•