Python a virtualenvwrapper: izolace pro vibecoding

Čisté prostředí je základní hygiena každého Python projektu a nastavíš ho za deset minut. Agent pak ví, kde kód běží, a ty se nezacyklíš. U Pythonu je tohle prostředí skoro vždycky virtuální prostředí (virtual environment).

V tomhle návodu ukážeme, proč izolace balíčků není zbytečná formalita, a projdeme praktický workflow s virtualenvwrapper, který v Python projektech používáme. Příkazy jsme ověřili v oficiální dokumentaci.

Krok 0: Nainstaluj Python

Máš Python? Ověř to v terminálu:

python3 --version

Pokud příkaz verzi nevypíše, stáhni aktuální Python z python.org/downloads. Návody pro Windows, macOS i Linux najdeš v oficiální sekci Using Python. Na macOS a Linuxu ho často máš předinstalovaný nebo ho dáš přes balíčkovací systém.

Zdroje: python.org/downloads, docs.python.org/3/using; ověřeno 2026-10-14.

Proč izolovat Python projekty

Na jednom počítači často běží víc projektů. Jeden chce Django 5, druhý starší knihovnu, třetí jinou verzi requests. Když je všechno nainstalované „globálně" do systémového Pythonu:

• balíčky si navzájem přepisují verze,
• projekt, který včera fungoval, dnes spadne,
• agent jako Claude Code nebo Cursor nainstaluje závislost „někam" a ty netušíš kam.

Virtuální prostředí je oddělená složka s vlastní kopií (nebo odkazem na) Pythonu a vlastním site-packages. Balíčky jednoho projektu nevidí balíčky druhého. Oficiální dokumentace Pythonu to popisuje stejně: prostředí je izolované od systémových balíčků a nemá se commitovat do Gitu.

Zdroj: venv — Creation of virtual environments; ověřeno 2026-10-14.

Proč právě virtualenvwrapper

Základní nástroj na izolaci je venv vestavěný v Pythonu. Funguje. My ale u denní práce s více projekty preferujeme virtualenvwrapper: sadu shell příkazů kolem virtualenv, které drží všechna prostředí na jednom místě (WORKON_HOME, výchozí ~/.virtualenvs) a umí je snadno vytvářet, přepínat a mazat.

Výhody, které v praxi cítíš:

• workon nazev místo hledání cesty k bin/activate,
• seznam všech prostředí přes lsvirtualenv nebo workon bez argumentu,
• konzistentní místo pro prostředí napříč projekty.

Zdroje: virtualenvwrapper – Installation, Command Reference; ověřeno 2026-10-14.

Instalace

virtualenvwrapper se instaluje do základního Pythonu, ne do aktivního virtuálního prostředí. Oficiální dokumentace varuje, že virtualenv i virtualenvwrapper patří jen na základní instalaci, aby je sdílela všechna prostředí.

pip install virtualenvwrapper
# nebo bez sudo, do uživatelského adresáře:
pip install --user virtualenvwrapper

Do shell startup souboru (např. ~/.bashrc nebo ~/.zshrc) přidej:

export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/Devel
source /usr/local/bin/virtualenvwrapper.sh

Cesta k virtualenvwrapper.sh se může lišit (např. po pip install --user). Najdi ji a uprav source řádek. Pak shell znovu načti:

source ~/.bashrc

Testováno oficiálně pod bash a zsh. Dokumentace uvádí podporu Pythonu 3.8–3.11.

Zdroj: Installation; ověřeno 2026-10-14.

Základní příkazy

Vytvoř prostředí: mkvirtualenv

mkvirtualenv mujprojekt

Vytvoří nové prostředí ve WORKON_HOME a hned ho aktivuje. Volitelně:

mkvirtualenv -r requirements.txt mujprojekt   # hned nainstaluj balíčky ze souboru
mkvirtualenv -i requests mujprojekt           # nainstaluj balíček hned po vytvoření
mkvirtualenv -a ~/Devel/mujprojekt mujprojekt # sváž prostředí s adresářem projektu

Přepni se: workon

workon                # vypíše seznam prostředí
workon mujprojekt     # aktivuje prostředí

Vypiš prostředí: lsvirtualenv

lsvirtualenv      # podrobný výpis (výchozí)
lsvirtualenv -b   # stručný výpis

Vypni prostředí: deactivate

deactivate

Vrátí tě k systémovému Pythonu. Příkaz pochází z virtualenv, virtualenvwrapper kolem něj přidává hooky.

Smaž prostředí: rmvirtualenv

deactivate              # nejdřív vypni, pokud jsi v něm
rmvirtualenv mujprojekt

Dokumentace výslovně říká: před smazáním aktuálního prostředí musíš použít deactivate.

Zdroj: Command Reference; ověřeno 2026-10-14.

Workflow s requirements.txt

Typický cyklus u Python projektu:

1. mkvirtualenv mujprojekt (nebo workon mujprojekt, pokud už existuje).
2. Nainstaluj balíčky: pip install flask (nebo co projekt potřebuje).
3. Ulož přesný seznam: pip freeze > requirements.txt.
4. Commitni requirements.txt do Gitu (viz Git pro vibecodery).
5. Na jiném počítači: mkvirtualenv -r requirements.txt mujprojekt.

mkvirtualenv -r předá soubor přímo pip -r, jak popisuje dokumentace. Soubor requirements.txt patří do repozitáře. Složka prostředí (~/.virtualenvs/... nebo lokální .venv) do Gitu nepatří.

Proměnné prostředí a soubor .env

Hesla, API klíče a URL databáze nepatří do kódu. Patří do proměnných prostředí (environment variables). Lokálně je často držíš v souboru .env v kořeni projektu:

DATABASE_URL=postgres://localhost/mujprojekt
OPENAI_API_KEY=sk-...

Pravidla, která dodržujeme:

1. .env nikdy necommituj. Patří do .gitignore (v Git článku je to ukázané).
2. Do repa dej spíš .env.example s prázdnými nebo fiktivními hodnotami, ať ostatní (a AI agent) ví, co mají nastavit.
3. V kódu čti hodnoty přes os.environ nebo knihovnu typu python-dotenv. Knihovnu nainstaluj do virtuálního prostředí, ne globálně.

Když agent spouští tvůj kód, aktivované prostředí + načtené .env znamená, že vidí stejné závislosti a stejné tajné hodnoty jako ty. Bez toho tipuje.

Jak to pomáhá s AI agenty

Claude Code, Cursor i Codex umí spouštět příkazy v terminálu. Když mají čisté, aktivované prostředí:

• pip install míří do projektu, ne do systému,
• python app.py používá správný interpreter,
• testy vidí stejné balíčky jako ty.

Do CLAUDE.md nebo AGENTS.md proto patří i řádky typu:

## Python
- Virtuální prostředí přes virtualenvwrapper: `workon mujprojekt`
- Závislosti: `pip install -r requirements.txt`
- Nikdy necommituj `.env` ani složku prostředí

Víc o práci s agentem: Claude Code v praxi. Srovnání nástrojů: Claude Code vs Cursor vs Codex.

Stručně o alternativách

venv (vestavěný v Pythonu 3):

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
deactivate

Je oficiální a stačí na jeden projekt ve složce. Na správu mnoha prostředí je virtualenvwrapper pohodlnější.

uv: moderní rychlý nástroj na Python balíčky a prostředí. Hodí se, když chceš maximální rychlost. V tomhle článku ho jen zmiňujeme; náš denní Python workflow stojí na virtualenvwrapper.

Zdroj k venv: docs.python.org/3/library/venv.html; ověřeno 2026-10-14.

Shrnutí

1. Izolace není optional luxury: chrání projekty před sebou navzájem.
2. virtualenvwrapper ti dá mkvirtualenv, workon, deactivate, rmvirtualenv, lsvirtualenv.
3. Závislosti drž v requirements.txt, tajemství v .env (mimo Git).
4. AI agent bez aktivního prostředí tipuje. Ty mu prostředí připrav.

Až budeš mít prostředí, nauč se v něm bezpečně verzovat změny: Git pro vibecodery. A když pustíš do kódu agenta, drž se návodu na Claude Code.

Chceš checklist „nový Python projekt od nuly"? Přihlas se k odběru našeho newsletteru.