noiembrie 22, 2026
Laptop cu editor de cod și terminal, ilustrând folosirea unui mediu virtual Python .venv pentru un proiect.

Ai instalat Python și ai început un proiect, iar apoi ai descoperit că o bibliotecă necesară pentru el nu funcționează cu versiunea folosită de alt proiect? Sau ai instalat mai multe pachete direct în Python-ul sistemului și nu mai știi care aplicație depinde de fiecare? Mediile virtuale rezolvă această problemă prin separarea pachetelor și a dependențelor pentru fiecare proiect.

În acest ghid vei crea un mediu virtual cu instrumentul venv, îl vei activa în Windows, macOS și Linux, vei instala pachete cu pip și vei salva lista dependențelor pentru a putea recrea mediul pe alt calculator. Vom folosi un proiect simplu, fără să modificăm instalarea globală de Python.

Ce este un mediu virtual Python?

Un mediu virtual este un director separat care conține un interpretor Python și propriile directoare pentru pachetele instalate. Când lucrezi în acel mediu, comenzile Python și pip folosesc pachetele proiectului, nu lista globală a tuturor bibliotecilor instalate pe calculator.

Imaginează-ți două aplicații. Prima are nevoie de o versiune mai veche a unei biblioteci, iar a doua folosește o versiune mai nouă. Dacă instalezi totul în același loc, actualizarea făcută pentru un proiect poate afecta celălalt proiect. Cu două medii virtuale, fiecare aplicație își păstrează propriile dependențe.

Mediul virtual nu este o mașină virtuală și nu instalează un sistem de operare separat. Este o izolare la nivelul mediului Python și al pachetelor. Fișierele proiectului rămân în directorul obișnuit, iar mediul poate fi recreat atunci când este nevoie.

De ce este recomandat să folosești venv?

Modulul venv face parte din biblioteca standard Python și permite crearea mediilor virtuale fără să instalezi separat un instrument pentru această operație. Este o alegere potrivită pentru proiecte personale, exerciții, aplicații web, scripturi de automatizare și experimente cu biblioteci externe.

  • Separarea proiectelor: fiecare proiect poate avea propriile versiuni ale bibliotecilor.
  • Mai puține conflicte: instalarea unui pachet pentru o aplicație nu modifică automat mediul alteia.
  • Instalări fără privilegii de administrator: în mod normal, pachetele proiectului sunt instalate în directorul mediului virtual.
  • Reproducerea mediului: poți salva dependențele și le poți instala din nou pe alt calculator.
  • Protejarea Python-ului sistemului: eviți să modifici pachetele gestionate de sistemul de operare.

Documentația Python recomandă mediile virtuale tocmai pentru situațiile în care aplicațiile au nevoie de versiuni diferite ale acelorași biblioteci. Găsești explicațiile oficiale în capitolul Virtual Environments and Packages.

Verifică instalarea Python înainte de a crea mediul

Deschide terminalul în Windows, macOS sau Linux și verifică dacă Python poate fi pornit. Comanda diferă în funcție de sistem și de modul în care a fost instalat interpretorul.

Comenzi de verificare

# Windows
py --version

# macOS sau Linux
python3 --version

# Alternativ, dacă python este configurat în PATH
python --version

Dacă primești un număr de versiune, interpretorul este disponibil. Pe Windows, lansatorul py poate selecta versiunea instalată, în timp ce pe macOS și Linux este întâlnită frecvent comanda python3. În exemplele următoare folosim comanda potrivită sistemului tău; nu este necesar să le rulezi pe toate.

Dacă nu ai instalat încă Python, începe cu ghidul Python pentru începători, apoi revino aici după ce poți verifica versiunea din terminal.

Creează proiectul și mediul .venv

Alege un folder pentru proiect. În exemplul nostru îl vom numi proiect-python. Deschide terminalul și navighează în folderul în care vrei să îl creezi.

mkdir proiect-python
cd proiect-python

Creează apoi mediul virtual în subfolderul .venv. Numele cu punct la început este o convenție des folosită: indică faptul că directorul conține fișiere de lucru ale mediului și îl păstrează mai puțin vizibil în unele instrumente.

Windows

py -m venv .venv

macOS și Linux

python3 -m venv .venv

Dacă ai ales o anumită versiune de Python și aceasta este disponibilă printr-o comandă dedicată, o poți folosi la crearea mediului. De exemplu, python3.12 -m venv .venv creează mediul cu interpretorul apelat prin python3.12. Verifică versiunea disponibilă pe calculatorul tău înainte să folosești un astfel de nume.

După creare, structura proiectului va semăna cu aceasta:

proiect-python/
├── .venv/
├── main.py
├── requirements.txt
└── .gitignore

Directorul .venv va conține fișierele necesare mediului. Nu este nevoie să îl modifici manual. Creează fișierele aplicației lângă el, nu în interiorul mediului virtual.

Activează mediul virtual în Windows, macOS și Linux

Crearea mediului și activarea lui sunt două operații diferite. Crearea pregătește directorul, iar activarea configurează sesiunea curentă de terminal astfel încât comenzile python și pip să folosească mediul proiectului.

Windows PowerShell

.\.venv\Scripts\Activate.ps1

Dacă folosești Command Prompt, scriptul de activare este diferit:

.venv\Scripts\activate.bat

Dacă PowerShell refuză să ruleze scriptul din cauza politicii de execuție, nu modifica la întâmplare setările de securitate. Poți folosi Command Prompt sau poți apela direct interpretorul din mediu, de exemplu .\.venv\Scripts\python.exe -m pip --version. Această variantă nu depinde de activarea scriptului.

macOS și Linux

source .venv/bin/activate

După activare, promptul terminalului afișează de obicei numele mediului, de exemplu (.venv). Aspectul exact diferă în funcție de shell și de configurația terminalului. Important este ca executabilul Python selectat să provină din directorul mediului virtual.

Verifică dacă terminalul folosește mediul corect

Nu te baza doar pe apariția numelui (.venv) în prompt. Verifică executabilul Python și versiunea lui pip. Calea afișată trebuie să indice directorul proiectului și subfolderul mediului virtual.

python --version
python -m pip --version

Pentru o verificare suplimentară, poți afișa locația interpretorului:

python -c "import sys; print(sys.executable)"

Calea ar trebui să conțină proiect-python/.venv sau echivalentul Windows. Dacă indică instalarea globală, verifică dacă mediul a fost activat în terminalul în care lucrezi sau folosește direct calea către executabilul din .venv.

Instalează pachete cu pip în mediul virtual

După activare, poți instala biblioteci pentru proiect. Vom folosi requests, un pachet utilizat pentru efectuarea de cereri HTTP din Python. Instalează-l cu:

python -m pip install requests

Este util să folosești forma python -m pip în locul comenzii simple pip. Astfel, pip este pornit prin interpretorul Python pe care tocmai l-ai selectat, reducând riscul să instalezi accidental pachetul în alt mediu.

Poți verifica instalarea și versiunea pachetului astfel:

python -m pip show requests
python -c "import requests; print(requests.__version__)"

Dacă primești informațiile despre pachet și numărul versiunii, instalarea a reușit în interpretorul folosit de terminal. Pentru instalarea și administrarea pachetelor, consultă ghidul oficial PyPA despre pip și mediile virtuale.

Salvează dependențele într-un fișier requirements.txt

Când proiectul folosește mai multe biblioteci, este util să păstrezi o listă a pachetelor instalate. Comanda pip freeze afișează pachetele și versiunile detectate în mediul curent. Redirecționează rezultatul într-un fișier:

python -m pip freeze > requirements.txt

Fișierul va conține intrări de forma requests==versiune și alte dependențe instalate. Versiunile exacte sunt utile atunci când vrei să recreezi un mediu apropiat de cel folosit la dezvoltare. Totuși, pip freeze înregistrează starea pachetelor instalate în acel mediu; nu este, de unul singur, un sistem complet de blocare și rezolvare a dependențelor pentru orice proiect.

Pentru a instala ulterior dependențele într-un mediu nou, folosește:

python -m pip install -r requirements.txt

Rulează comanda după ce ai activat mediul virtual în care vrei să instalezi pachetele. Dacă proiectul are nevoie de o bibliotecă nouă, instaleaz-o în acel mediu și actualizează lista numai după ce ai verificat că aplicația funcționează în continuare.

Folosește .gitignore pentru a nu trimite mediul în repository

Directorul .venv poate conține multe fișiere specifice calculatorului pe care a fost creat. În mod obișnuit, nu îl adaugi în Git. În repository păstrezi codul sursă și fișierul requirements.txt, iar fiecare persoană își creează propriul mediu virtual local.

Creează în rădăcina proiectului un fișier numit .gitignore și adaugă:

.venv/
__pycache__/
*.py[cod]
.env

Ultima regulă exclude un posibil fișier local cu variabile de configurare, care poate conține chei sau parole. Verifică întotdeauna ce date păstrezi în fișierele proiectului și nu publica secrete în repository. Dacă nu ai folosit încă Git, poți urma ghidul Git și GitHub pentru începători.

Selectează mediul .venv în Visual Studio Code

Dacă folosești Visual Studio Code, deschide folderul principal al proiectului, nu doar un fișier izolat. Instalează extensia oficială Python publicată de Microsoft, apoi deschide paleta de comenzi și caută Python: Select Interpreter. Pașii și opțiunile actuale sunt descrise în documentația Visual Studio Code despre mediile Python.

Alege interpretorul din directorul .venv. În Windows, calea se termină de regulă în .venv\Scripts\python.exe, iar pe macOS și Linux în .venv/bin/python. După selecție, terminalele noi și rularea fișierelor Python ar trebui să folosească mediul ales, dar verifică întotdeauna calea interpretorului dacă rezultatele nu corespund așteptărilor.

Dacă mediul nu apare în listă, verifică dacă directorul .venv există și dacă proiectul este deschis din folderul corect. Poți selecta manual interpretorul prin opțiunea de introducere a căii către executabilul Python din acel director.

Dezactivează, recreează sau șterge mediul virtual

Când ai terminat lucrul în terminal, poți dezactiva mediul cu aceeași comandă pe Windows, macOS și Linux:

deactivate

Dezactivarea modifică doar sesiunea curentă de terminal. Nu dezinstalează pachetele și nu șterge mediul virtual. La următoarea sesiune, activează din nou mediul înainte să rulezi proiectul sau să instalezi dependențe.

Dacă mediul s-a deteriorat sau vrei să îl reconstruiești, închide programele care îl folosesc, dezactivează-l și șterge directorul .venv. Apoi creează-l din nou și instalează dependențele din fișierul salvat:

# Creează din nou mediul
py -m venv .venv

# Activează-l în PowerShell
.\.venv\Scripts\Activate.ps1

# Reinstalează dependențele
python -m pip install -r requirements.txt

Pe macOS și Linux înlocuiește prima comandă cu python3 -m venv .venv, iar activarea cu source .venv/bin/activate. Pentru ștergerea directorului folosește instrumentul obișnuit al sistemului de operare și verifică de două ori calea înainte să confirmi eliminarea.

Probleme frecvente și soluții

Comanda python -m venv nu funcționează

Verifică versiunea și calea interpretorului. Pe unele distribuții Linux, modulul pentru crearea mediilor virtuale este furnizat într-un pachet separat al distribuției. Instalează pachetul recomandat de managerul de pachete al sistemului, apoi încearcă din nou. Nu descărca arhive necunoscute pentru a înlocui modulul lipsă.

pip instalează pachetul în altă locație

Verifică dacă mediul este activ și execută python -m pip --version. Calea afișată trebuie să indice mediul proiectului. Evită să folosești comenzi pip fără să știi la ce interpretor sunt asociate.

Primești o eroare de mediu gestionat extern pe Linux

Unele distribuții marchează instalarea Python de sistem ca fiind gestionată de managerul lor de pachete. În această situație, nu forța instalarea globală și nu folosi opțiuni care dezactivează protecția fără să înțelegi consecințele. Creează un mediu cu python3 -m venv .venv și instalează pachetele proiectului în acel mediu. Dacă modulul venv lipsește, instalează componenta corespunzătoare prin managerul distribuției.

Modulul este instalat, dar Python nu îl găsește

Este posibil să rulezi proiectul cu alt interpretor decât cel în care ai instalat pachetul. Compară rezultatul comenzii python -c "import sys; print(sys.executable)" cu locația mediului și selectează interpretorul corect în editor. Repetă instalarea folosind python -m pip install nume-pachet numai după ce ai confirmat interpretorul.

venv, virtualenv și pipx: ce instrument alegi?

venv este inclus în biblioteca standard Python și este suficient pentru majoritatea proiectelor obișnuite. virtualenv este un instrument separat, cu funcții suplimentare și suport pentru scenarii în care ai nevoie de o gestionare diferită a mediilor. pipx are alt scop: instalează aplicații Python de linie de comandă în medii izolate, astfel încât instrumentele să nu se amestece cu dependențele proiectelor tale.

Pentru un proiect nou în care scrii cod Python și instalezi biblioteci, începe cu venv și pip. Dacă vrei să instalezi o aplicație de terminal distribuită prin PyPI, analizează pipx. Ghidul PyPA prezintă și recomandările pentru instrumentele din ecosistemul Python.

Un flux simplu pe care îl poți repeta la fiecare proiect

Pentru proiectele noi, păstrează aceeași rutină: creează folderul, inițializează mediul, activează-l, instalează numai pachetele necesare și salvează dependențele. Înainte să trimiți codul către GitHub, verifică fișierul .gitignore și asigură-te că nu incluzi directorul mediului sau secrete locale.

După ce ai înțeles acest flux, poți trece la proiecte care consumă date de pe internet. Ghidul despre API-uri și primul request HTTP este un pas potrivit: poți crea un mediu separat, instala requests și testa o cerere fără să modifici pachetele altor aplicații.

Pentru documentație completă și actualizată, păstrează la îndemână referința oficială pentru modulul venv și ghidul Python Packaging User Guide. Acestea explică opțiunile și particularitățile care pot diferi între versiuni și sisteme de operare.


Descoperă mai multe la Scoala IT

Abonează-te ca să primești ultimele articole prin email.

Descoperă mai multe la Scoala IT

Abonează-te acum ca să citești în continuare și să ai acces la întreaga arhivă.

Continuă lectura