Virtual environment na Ubuntu – instrukcja tworzenia krok po kroku

Virtual environment na Ubuntu pozwala utworzyć odizolowane środowisko dla projektu Python. Dzięki temu biblioteki potrzebne do jednego projektu nie mieszają się z zależnościami innych aplikacji.

W tym poradniku pokazuję krok po kroku, jak utworzyć virtual environment na Ubuntu, jak go aktywować, instalować pakiety za pomocą pip, zapisywać zależności w requirements.txt oraz odtwarzać środowisko na innej maszynie.

Jeżeli dopiero przygotowujesz Ubuntu do pracy, możesz wcześniej sprawdzić poradnik dotyczący instalacji Oracle VirtualBox oraz instrukcję instalacji maszyny wirtualnej Ubuntu 26.04 w Oracle VirtualBox.

Czym jest virtual environment na Ubuntu i dlaczego je tworzymy?

Virtual environment na Ubuntu to odizolowane środowisko Pythona przeznaczone dla konkretnego projektu. Tworzenie virtual environment ma przede wszystkim jeden cel: odizolowanie bibliotek i zależności konkretnego projektu od pozostałych projektów oraz systemowego środowiska Python.

Wyobraź sobie, że na jednym komputerze pracujesz nad trzema projektami:

Projekt A → Python + biblioteki A 
Projekt B → Python + biblioteki B 
Projekt C → Python + biblioteki C

Instalowanie wszystkich bibliotek globalnie może doprowadzić do konfliktów między projektami. Każdy z tych projektów może wymagać innych bibliotek, a nawet innych wersji tych samych bibliotek.

Gdyby wszystkie pakiety były instalowane globalnie, mogłoby dojść do sytuacji, w której instalacja lub aktualizacja biblioteki potrzebnej dla jednego projektu wpłynie na działanie innego projektu.

Virtual environment pozwala tego uniknąć.

Projekt A → biblioteka X w wersji 1.0
Projekt B → biblioteka X w wersji 2.0
Projekt C → biblioteka X w wersji 2.1

Virtual environment pozwala utworzyć osobne środowisko dla każdej aplikacji:

Projekt_A
└── .venv
    └── biblioteki projektu A

Projekt_B
└── .venv
    └── biblioteki projektu B

Projekt_C
└── .venv
    └── biblioteki projektu C

Każdy projekt może dzięki temu posiadać własne zależności. Dzięki takiemu podejściu biblioteki zainstalowane w .venv projektu A są niezależne od bibliotek znajdujących się w .venv projektu B i w .venv projektu C.

Co daje takie odizolowanie?

Załóżmy, że w jednym projekcie instalujesz:

python -m pip install requests

Pakiet zostanie zainstalowany w aktywnym virtual environment TYLKO tego projektu. Nie instalujesz go wtedy jako globalnej biblioteki dostępnej dla wszystkich projektów.

Możesz więc mieć:

projekt-a/
└── .venv/
    └── biblioteki projektu A, np. request

projekt-b/
└── .venv/
    └── biblioteki projektu B, np. numpy

Każde środowisko może mieć własny zestaw pakietów i własne wersje bibliotek. Jest to szczególnie przydatne podczas pracy nad projektami wykorzystującymi biblioteki takie jak numpy, pandas, scikit-learn, torch, transformers czy inne pakiety, których wersje mogą mieć znaczenie dla działania aplikacji.

Ubuntu w swojej dokumentacji również zaleca korzystanie ze środowisk wirtualnych podczas instalowania zależności projektów Python. Oficjalna dokumentacja Ubuntu dotycząca Pythona pokazuje wykorzystanie venv do tworzenia odizolowanego środowiska.

Dlaczego warto korzystać z virtual environment na Ubuntu?

Korzystanie z virtual environment jest szczególnie przydatne, kiedy na jednym komputerze lub serwerze znajduje się kilka projektów Python.

Najważniejsze zalety to:

• izolacja bibliotek poszczególnych projektów,
• ograniczenie konfliktów między wersjami pakietów,
• możliwość stosowania różnych zależności w różnych projektach,
• łatwiejsze przenoszenie aplikacji,
• możliwość zapisania zależności w requirements.txt,
• ograniczenie potrzeby instalowania bibliotek globalnie.

Virtual environment przydaje się zarówno na komputerze użytkownika, jak i na serwerze Ubuntu czy maszynie wirtualnej.

Jak utworzyć virtual environment na Ubuntu?

1. Sprawdź wersję Pythona

Pierwszym krokiem jest sprawdzenie, czy Python 3 jest zainstalowany.

Otwórz terminal i wpisz:

python3 --version

Przykładowy wynik:

Python 3.12.3

Wersja Pythona zależy od używanej wersji Ubuntu.

Możesz również sprawdzić lokalizację interpretera:

which python3

2. Zainstaluj pakiet python3-venv

Jeżeli system nie posiada komponentu potrzebnego do tworzenia środowisk wirtualnych, zainstaluj:

sudo apt update
sudo apt install python3-venv 
sudo apt install python3-pip

Pakiet python3-venv dostarcza moduł venv, który jest wykorzystywany do tworzenia środowisk wirtualnych.

W razie potrzeby możesz również zainstalować pełne środowisko Python:

sudo apt install python3-full

Oficjalna dokumentacja Ubuntu opisuje instalację python3-full oraz korzystanie z venv w konfiguracji środowiska Python. Sprawdź dokumentację Ubuntu dotyczącą konfiguracji Pythona.

3. Utwórz katalog projektu

Załóżmy, że tworzysz projekt o nazwie myfirstproject.

Wpisz:

mkdir workspace
cd workspace

mkdir myfirstproject
cd myfirstproject

Możesz sprawdzić bieżącą lokalizację:

pwd

4. Utwórz virtual environment na Ubuntu

Będąc w katalogu projektu, możesz utworzyć virtual environment za pomocą polecenia:

python3 -m venv .venv

W tym poleceniu:

• python3 – uruchamia interpreter Python 3 dostępny w systemie,
• -m venv – uruchamia moduł venv, który służy do tworzenia środowisk wirtualnych,
• .venv – określa nazwę katalogu, w którym zostanie utworzone środowisko.

Po wykonaniu polecenia zostanie utworzony katalog:

.venv/

Struktura projektu będzie wyglądać następująco:

myfirstproject/
└── .venv/

Czy virtual environment na Ubuntu musi nazywać się .venv?

Nie. Nazwa virtual environment może być dowolna. Nazwa.venv jest jedynie bardzo popularną konwencją stosowaną w projektach Python. Kropka na początku nazwy sprawia, że katalog jest traktowany jako ukryty w systemach Linux. Możesz więc utworzyć środowisko o nazwie:

python3 -m venv .venv

albo:

python3 -m venv venv

Możesz również użyć własnej nazwy, na przykład:

python3 -m venv .takasobiezmienna

albo:

python3 -m venv python-env

W każdym przypadku mechanizm działania jest taki sam. Zmienia się tylko nazwa katalogu, w którym zostanie utworzone środowisko.

Przykładowo:

python3 -m venv python-env

utworzy strukturę:

myfirstproject/
└── python-env/

W tym poradniku będziemy korzystać ze standardowej nazwy .venv.

5. Aktywuj virtual environment

Samo utworzenie środowiska nie oznacza jeszcze jego aktywacji.

Na Ubuntu wykonaj:

source .venv/bin/activate

Jeżeli aktywacja przebiegła prawidłowo, na początku wiersza terminala pojawi się:

(.venv)

Na przykład:

(.venv) Student@OSINT-Ubuntu-24:~/workspace/myfirstproject$

Od tego momentu pracujesz w środowisku projektu.

6. Sprawdź, z jakiego interpretera korzystasz

Po aktywowaniu środowiska możesz sprawdzić, z jakiego interpretera Python aktualnie korzysta terminal. Interpreter Python to program, który wykonuje kod napisany w języku Python. To właśnie interpreter uruchamia pliki .py i wykonuje zawarte w nich instrukcje.

Możesz sprawdzić jego lokalizację za pomocą:

which python

Jeżeli virtual environment jest aktywny, wynik powinien wskazywać na interpreter znajdujący się wewnątrz katalogu tego środowiska, na przykład:

/home/Student/workspace/myfirstproject/.venv/bin/python

Oznacza to, że polecenie python korzysta z interpretera należącego do środowiska .venv, a nie z systemowego interpretera Python.

Możesz również sprawdzić lokalizację programu pip:

which pip

Powinien pojawić się podobny wynik:

//home/Student/workspace/myfirstproject/.venv/bin/pip

Dzięki temu możesz upewnić się, że zarówno Python, jak i pip pochodzą z tego samego virtual environment.

Jest to szczególnie ważne, ponieważ pakiety instalowane przez pip powinny trafiać do tego samego środowiska, z którego uruchamiasz program Python. Dzięki temu unikniesz sytuacji, w której pakiet zostanie zainstalowany w systemowym Pythonie zamiast w środowisku projektu.

Jeżeli ścieżka zawiera .venv, oznacza to, że korzystasz z właściwego środowiska.

Możesz też sprawdzić wersję interpretera:

python --version

Przykładowo:

Python 3.12.3

W praktyce warto przed rozpoczęciem pracy wykonać:

which python
python --version
which pip

To szybki sposób na sprawdzenie, z jakiego interpretera Python korzystasz i gdzie instalowane są pakiety.

7. Zaktualizuj pip

Po aktywowaniu virtual environment warto zaktualizować pip:

python -m pip install --upgrade pip

Zalecane jest korzystanie z:

python -m pip

zamiast:

pip

Takie wywołanie jednoznacznie wskazuje, że pip ma być uruchomiony przez aktualnie używanego Pythona.

8. Zainstaluj bibliotekę w virtual environment

Załóżmy, że projekt potrzebuje biblioteki requests.

Wykonaj następujące polecenie:

python -m pip install requests

Pakiet zostanie zainstalowany wewnątrz virtual environment.

Listę zainstalowanych bibliotek możesz sprawdzić poleceniem:

python -m pip list

Wynik powinien być podobny do tego poniżej:

Package    Version
---------- -------
pip        26.2.1
requests   2.34.2

9. Zapisz zależności projektu w requirements.txt

Jeżeli chcesz przenieść projekt na inną maszynę, warto zapisać listę jego zależności.

Wykonaj:

python -m pip freeze > requirements.txt

W katalogu projektu znajdzie się teraz:

myfirstproject/
├── .venv/
└── requirements.txt

Plik można można otworzyć np. w Visual Studio Code za pomocą polecenia code .:

Przykładowa zawartość pliku:

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

Plik requirements.txt pozwala łatwo odtworzyć środowisko projektu.code

10. Jak odtworzyć virtual environment na innej maszynie?

Załóżmy, że przenosisz projekt na drugi komputer lub serwer Ubuntu.

Najpierw przejdź do katalogu projektu, który musisz najpierw utworzyć na nowej maszynie:

cd myfirstproject

Następnie utwórz środowisko (virtual environment):

python3 -m venv .venv

Aktywuj je:

source .venv/bin/activate

Następnie zainstaluj zależności:

python -m pip install -r requirements.txt

Wszystkie pakiety zapisane w requirements.txt zostaną zainstalowane w nowym środowisku. Dzięki temu nie musisz ponownie instalować każdej biblioteki ręcznie.

11. Jak wyłączyć virtual environment na Ubuntu?

Jeżeli kończysz pracę z jednym projektem i chcesz rozpocząć pracę z innym, najpierw dezaktywuj aktualnie używane virtual environment.

W tym celu wykonaj polecenie:

deactivate

Po wykonaniu tego polecenia oznaczenie aktywnego środowiska, na przykład: .venv zniknie z terminala. Sam katalog z virtual environment nie zostanie usunięty. Polecenie deactivate jedynie powoduje, że terminal przestaje korzystać z interpretera Python i pakietów należących do tego środowiska.

Jest to szczególnie ważne, gdy pracujesz jednocześnie nad kilkoma projektami.

Załóżmy, że masz dwa projekty:

myfirstproject/
└── .venv/

ai-project/
└── .ai-venv/

Podczas pracy nad pierwszym projektem terminal może wyglądać tak, jak na screnach i w opisie powyżej:

(.venv) Student@OSINT-Ubuntu-24:~/workspace/myfirstproject$

Jeżeli chcesz teraz rozpocząć pracę nad projektem AI, najpierw wykonaj:

deactivate

Następnie przejdź do katalogu drugiego projektu:

cd ..
cd ai-project

i aktywuj jego środowisko:

source ai-env/bin/activate

Terminal powinien teraz wskazywać:

(.ai-venv) Student@OSINT-Ubuntu-24:~/workspace/ai-project$

Dlaczego różne nazwy środowisk mogą być przydatne?

Właśnie podczas pracy z wieloma projektami dobrze widać zaletę nadawania środowiskom różnych, charakterystycznych nazw.

Jeżeli każde środowisko nazywa się .venv, w terminalu zawsze zobaczysz:

(.venv)

Nie oznacza to, że jest to to samo środowisko — każdy projekt może mieć własny, całkowicie niezależny katalog .venv. Jednak na pierwszy rzut oka trudniej rozpoznać, które środowisko jest aktualnie aktywne.

Jeżeli zastosujesz nazwy związane z projektami, na przykład:

(.monitoring-venv)
(.ai-venv)
(.malware-analysis-venv)

znacznie łatwiej zauważyć, z którym środowiskiem aktualnie pracujesz.

To może pomóc uniknąć prostego, ale częstego błędu: przejścia do katalogu innego projektu bez wcześniejszej dezaktywacji poprzedniego środowiska.

Samo przejście do innego katalogu za pomocą cd nie dezaktywuje virtual environment.

Dlatego dobrym nawykiem jest stosowanie schematu:

deactivate
cd ..
cd inny-projekt
source nazwa-srodowiska/bin/activate

Dopiero wtedy rozpocznij instalowanie bibliotek, uruchamianie skryptów czy dalszą pracę z Pythonem.

Dzięki temu każdy projekt korzysta z własnego interpretera Python i własnego zestawu bibliotek, a zależności różnych projektów nie mieszają się ze sobą.

12. Jak ponownie aktywować virtual environment?

Kiedy wrócisz do projektu, nie musisz tworzyć środowiska ponownie.

Przejdź do katalogu projektu:

cd ..
cd myfirstproject

Następnie wykonaj:

source .venv/bin/activate

Virtual environment zostanie ponownie aktywowane i dostęp do zainstalowanych bibliotek przywrócony.

13. Virtual environment a Git

Jeżeli projekt jest przechowywany w repozytorium Git, nie należy dodawać katalogu .venv do repozytorium.

Dodaj plik .gitignore do pojektu:

touch .gitignore

Możesz zrobić to poleceniem:

Dodaj do .gitignore:

.venv/

Możesz zrobić to poleceniem:

echo ".venv/" >> .gitignore

Do repozytorium warto natomiast dodać:

requirements.txt

Dzięki temu inne osoby mogą utworzyć własne środowisko za pomocą poniższych poleceń:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Szablony plików .gitignore dla różnych języków można znaleźć w tym repozytorium na Githubie.

Virtual environment na Ubuntu można łatwo usunąć i utworzyć ponownie

Jedną z dużych zalet virtual environment jest to, że nie trzeba traktować go jako czegoś trwałego i nienaruszalnego.

Środowisko można w każdej chwili usunąć i utworzyć ponownie.

Załóżmy, że masz projekt:

myfirstproject/
├── .venv/
├── .gitignore
├── app.py
└── requirements.txt

W .venv znajdują się wszystkie biblioteki zainstalowane dla tego projektu.

Jeżeli środowisko przestanie działać prawidłowo, zostanie zaśmiecone testowymi pakietami albo chcesz po prostu rozpocząć pracę z czystym środowiskiem, możesz je usunąć.

Najpierw wyłącz środowisko:

deactivate

Następnie usuń katalog:

rm -rf .venv

To polecenie usuwa wyłącznie virtual environment znajdujące się w katalogu .venv. Nie usuwa Twojego projektu, kodu źródłowego ani innych plików znajdujących się w katalogu projektu.

Pozostają na przykład:

myfirstproject/
├── .gitignore
├── app.py
├── requirements.txt
└── ...

Możesz teraz utworzyć zupełnie nowe środowisko:

python3 -m venv .venv

Aktywować je:

source .venv/bin/activate

I ponownie zainstalować zależności projektu:

python -m pip install -r requirements.txt

W ten sposób otrzymujesz czyste środowisko, bez konieczności usuwania lub ponownej instalacji całego Pythona w systemie.

To trochę jak „reset” środowiska projektu

Można więc potraktować virtual environment jako wymienne środowisko pracy dla konkretnego projektu.

Jeżeli eksperymentujesz z bibliotekami, instalujesz i usuwasz pakiety, testujesz różne wersje zależności albo wykonujesz ćwiczenia programistyczne, nie musisz obawiać się, że zaśmiecisz systemowego Pythona.

W najgorszym przypadku możesz:

1. wyłączyć środowisko,
2. usunąć katalog .venv,
3. utworzyć nowe środowisko,
4. ponownie zainstalować zależności z requirements.txt.

Czyli:

deactivate
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Kod projektu pozostaje nietknięty. Usuwasz tylko środowisko oraz biblioteki zainstalowane w ramach tego środowiska.

To właśnie jedna z najważniejszych praktycznych zalet korzystania z virtual environment podczas pracy z Pythonem.

Czy warto instalować biblioteki Python globalnie?

W przypadku zależności konkretnego projektu lepiej korzystać z virtual environment.

Zamiast instalować pakiet bezpośrednio w systemowym środowisku Python:

pip install NAZWA_PAKIETU

utwórz środowisko:

python3 -m venv .venv

aktywuj je:

source .venv/bin/activate

i dopiero wtedy instaluj pakiety:

python -m pip install NAZWA_PAKIETU

Takie podejście ogranicza ryzyko konfliktów z pakietami używanymi przez inne aplikacje.

Warto również uważać na komunikat:

externally-managed-environment

Może on pojawić się podczas próby instalowania pakietów pip do środowiska zarządzanego przez system. W takim przypadku jednym z właściwych rozwiązań jest utworzenie virtual environment.

Virtual environment na Ubuntu – najważniejsze polecenia

Zadanie	Polecenie
Sprawdzenie Pythona	python3 --version
Instalacja venv	sudo apt install python3-venv
Utworzenie środowiska	python3 -m venv .venv
Aktywacja	source .venv/bin/activate
Sprawdzenie interpretera	which python
Aktualizacja pip	python -m pip install --upgrade pip
Instalacja pakietu	python -m pip install NAZWA
Lista pakietów	python -m pip list
Zapis zależności	python -m pip freeze > requirements.txt
Instalacja zależności	python -m pip install -r requirements.txt
Wyłączenie środowiska	deactivate

---

Virtual environment na Ubuntu – szybki przykład

Jeżeli potrzebujesz tylko najważniejszych poleceń, możesz wykonać:

sudo apt update
sudo apt install python3-venv python3-pip

mkdir moj-projekt
cd moj-projekt

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install requests

Po zakończeniu pracy:

deactivate

Przy kolejnym uruchomieniu projektu:

cd moj-projekt
source .venv/bin/activate

---

Virtual environment na Ubuntu – FAQ

Czy virtual environment instaluje osobnego Pythona?

Nie jest to pełna, niezależna instalacja systemu Python. venv tworzy odizolowane środowisko związane z interpreterem Pythona, którego użyto do jego utworzenia.

Czy każdy projekt Python powinien mieć własne środowisko?

Jest to zalecana praktyka. Dzięki temu każdy projekt może mieć własne wersje bibliotek i niezależne zależności.

Czy katalog .venv trzeba dodawać do Git?

Nie. Katalog .venv powinien być zazwyczaj dodany do .gitignore.

Czy po restarcie Ubuntu trzeba tworzyć środowisko ponownie?

Nie. Wystarczy ponownie je aktywować za pomocą polecenia:

source .venv/bin/activate

Czy można usunąć virtual environment?

Tak. Po wyłączeniu środowiska możesz usunąć katalog .venv:

rm -rf .venv

Spowoduje to usunięcie środowiska wraz ze znajdującymi się w nim bibliotekami.

Podsumowanie

Virtual environment na Ubuntu pozwala stworzyć odizolowane środowisko Python dla konkretnego projektu. Jest to proste rozwiązanie, które pomaga zarządzać bibliotekami i ograniczać konflikty między zależnościami.

Najważniejsze polecenia to:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install NAZWA_PAKIETU
deactivate

Jeżeli projekt ma być przenoszony na inną maszynę, warto dodatkowo utworzyć:

python -m pip freeze > requirements.txt

a następnie na nowej maszynie użyć:

python -m pip install -r requirements.txt

Jeżeli przygotowujesz środowisko Ubuntu w maszynie wirtualnej, zacznij od instalacji Oracle VirtualBox, a następnie przejdź do poradnika instalacji Ubuntu 26.04 w Oracle VirtualBox.