Віртуальні середовища¶

🌐 Переклад ШІ та людьми

Цей переклад виконано ШІ під керівництвом людей. 🤝

Можливі помилки через неправильне розуміння початкового змісту або неприродні формулювання тощо. 🤖

Ви можете покращити цей переклад, допомігши нам краще спрямовувати AI LLM.

Коли ви працюєте над проєктами Python, вам, імовірно, слід використовувати віртуальне середовище (або схожий механізм), щоб ізолювати пакети, які ви встановлюєте для кожного проєкту.

Інформація

Якщо ви вже знаєте про віртуальні середовища, як їх створювати та використовувати, можете пропустити цей розділ. 🤓

Порада

Віртуальне середовище відрізняється від змінної оточення.

Змінна оточення - це змінна в системі, яку можуть використовувати програми.

Віртуальне середовище - це каталог із файлами в ньому.

Інформація

На цій сторінці ви дізнаєтеся, як використовувати віртуальні середовища і як вони працюють.

Якщо ви готові прийняти інструмент, що керує всім за вас (включно з установленням Python), спробуйте uv.

Створіть проєкт¶

Спочатку створіть каталог для вашого проєкту.

Зазвичай я створюю каталог з назвою code у моєму домашньому каталозі користувача.

І всередині нього я створюю окремий каталог на кожен проєкт.

// Перейдіть до домашнього каталогу
$ cd
// Створіть каталог для всіх ваших проєктів з кодом
$ mkdir code
// Перейдіть у цей каталог code
$ cd code
// Створіть каталог для цього проєкту
$ mkdir awesome-project
// Перейдіть до каталогу цього проєкту
$ cd awesome-project

Створіть віртуальне середовище¶

Коли ви починаєте працювати над проєктом Python уперше, створіть віртуальне середовище у вашому проєкті у вашому проєкті.

Порада

Це потрібно робити лише один раз на проєкт, не щоразу, коли ви працюєте.

venvuv

Щоб створити віртуальне середовище, ви можете використати модуль venv, який постачається разом із Python.

$ python -m venv .venv

Що означає ця команда

python: використати програму з назвою python
-m: викликати модуль як скрипт, далі ми вкажемо, який модуль
venv: використати модуль з назвою venv, який зазвичай уже встановлено з Python
.venv: створити віртуальне середовище в новому каталозі .venv

Якщо у вас встановлено uv, ви можете використати його для створення віртуального середовища.

$ uv venv

Порада

Типово uv створить віртуальне середовище в каталозі з назвою .venv.

Але ви можете налаштувати це, передавши додатковий аргумент з назвою каталогу.

Ця команда створює нове віртуальне середовище в каталозі з назвою .venv.

.venv або інша назва

Ви можете створити віртуальне середовище в іншому каталозі, але існує усталена домовленість називати його .venv.

Активуйте віртуальне середовище¶

Активуйте нове віртуальне середовище, щоб будь-яка команда Python, яку ви запускаєте, або пакет, який ви встановлюєте, використовували його.

Порада

Робіть це щоразу, коли ви починаєте нову сесію термінала для роботи над проєктом.

Linux, macOSWindows PowerShellWindows Bash

$ source .venv/bin/activate

$ .venv\Scripts\Activate.ps1

Або якщо ви використовуєте Bash для Windows (напр., Git Bash):

$ source .venv/Scripts/activate

Порада

Кожного разу, коли ви встановлюєте новий пакет у це середовище, активуйте середовище знову.

Це гарантує, що якщо ви використовуєте програму термінала (CLI), встановлену цим пакетом, ви використовуєте саме ту з вашого віртуального середовища, а не будь-яку іншу, яка може бути встановлена глобально, імовірно з іншою версією, ніж вам потрібно.

Перевірте активність віртуального середовища¶

Перевірте, що віртуальне середовище активне (попередня команда спрацювала).

Порада

Це необов'язково, але це гарний спосіб перевірити, що все працює як очікується і ви використовуєте саме те віртуальне середовище, яке планували.

Linux, macOS, Windows BashWindows PowerShell

$ which python

/home/user/code/awesome-project/.venv/bin/python

Якщо показано бінарний файл python за шляхом .venv/bin/python усередині вашого проєкту (у цьому випадку awesome-project), тоді все спрацювало. 🎉

$ Get-Command python

C:\Users\user\code\awesome-project\.venv\Scripts\python

Якщо показано бінарний файл python за шляхом .venv\Scripts\python усередині вашого проєкту (у цьому випадку awesome-project), тоді все спрацювало. 🎉

Оновіть `pip`¶

Порада

Якщо ви використовуєте uv, ви використовуватимете його для встановлення замість pip, тож вам не потрібно оновлювати pip. 😎

Якщо ви використовуєте pip для встановлення пакетів (він іде за замовчуванням із Python), вам слід оновити його до найновішої версії.

Багато дивних помилок під час встановлення пакета вирішуються тим, що спочатку оновлюють pip.

Порада

Зазвичай це роблять один раз, відразу після створення віртуального середовища.

Переконайтеся, що віртуальне середовище активне (командою вище), а потім виконайте:

$ python -m pip install --upgrade pip

---> 100%

Порада

Іноді ви можете отримати помилку No module named pip при спробі оновити pip.

Якщо це сталося, встановіть і оновіть pip за допомогою команди нижче:

$ python -m ensurepip --upgrade

---> 100%

Ця команда встановить pip, якщо він ще не встановлений, і також гарантує, що встановлена версія pip принаймні така ж нова, як доступна в ensurepip.

Додайте `.gitignore`¶

Якщо ви використовуєте Git (варто це робити), додайте файл .gitignore, щоб виключити з Git усе у вашому .venv.

Порада

Якщо ви використали uv для створення віртуального середовища, він уже зробив це за вас, можете пропустити цей крок. 😎

Порада

Зробіть це один раз, відразу після створення віртуального середовища.

$ echo "*" > .venv/.gitignore

Що означає ця команда

echo "*": «виведе» текст * у термінал (наступна частина трохи це змінює)
>: усе, що команда ліворуч від > «виводить» у термінал, не слід друкувати, натомість записати у файл, вказаний праворуч від >
.gitignore: назва файлу, куди слід записати текст

А * для Git означає «все». Тож він ігноруватиме все в каталозі .venv.

Ця команда створить файл .gitignore із вмістом:

Встановіть пакети¶

Після активації середовища ви можете встановлювати в нього пакети.

Порада

Робіть це один раз під час встановлення або оновлення пакетів, потрібних вашому проєкту.

Якщо вам потрібно оновити версію або додати новий пакет, ви зробите це знову.

Встановіть пакети безпосередньо¶

Якщо ви поспішаєте та не хочете використовувати файл для оголошення вимог вашого проєкту до пакетів, ви можете встановити їх безпосередньо.

Порада

Дуже добра ідея - записати пакети та версії, потрібні вашій програмі, у файл (наприклад, requirements.txt або pyproject.toml).

pipuv

$ pip install "fastapi[standard]"

---> 100%

Якщо у вас є uv:

$ uv pip install "fastapi[standard]"
---> 100%

Встановіть з `requirements.txt`¶

Якщо у вас є requirements.txt, ви можете використати його для встановлення перелічених там пакетів.

pipuv

$ pip install -r requirements.txt
---> 100%

Якщо у вас є uv:

$ uv pip install -r requirements.txt
---> 100%

requirements.txt

requirements.txt із деякими пакетами може виглядати так:

fastapi[standard]==0.113.0
pydantic==2.8.0

Запустіть вашу програму¶

Після активації віртуального середовища ви можете запустити вашу програму, і вона використовуватиме Python із вашого віртуального середовища з пакетами, які ви там встановили.

$ python main.py

Hello World

Налаштуйте ваш редактор¶

Ймовірно, ви використовуєте редактор коду, переконайтеся, що ви налаштували його на використання того самого віртуального середовища, яке ви створили (швидше за все, він визначить його автоматично), щоб отримувати автодоповнення та підсвічування помилок.

Наприклад:

Порада

Зазвичай це потрібно робити лише один раз, коли ви створюєте віртуальне середовище.

Деактивуйте віртуальне середовище¶

Коли ви завершили роботу над проєктом, ви можете деактивувати віртуальне середовище.

$ deactivate

Таким чином, коли ви запустите python, він не намагатиметься запускатися з того віртуального середовища з установленими там пакетами.

Готові до роботи¶

Тепер ви готові почати працювати над вашим проєктом.

Порада

Хочете зрозуміти, що це все було вище?

Продовжуйте читати. 👇🤓

Навіщо віртуальні середовища¶

Щоб працювати з FastAPI, вам потрібно встановити Python.

Після цього вам потрібно буде встановити FastAPI та інші пакети, які ви хочете використовувати.

Для встановлення пакетів зазвичай використовують команду pip, що постачається з Python (або схожі альтернативи).

Однак, якщо ви просто користуватиметеся pip напряму, пакети встановлюватимуться у ваше глобальне середовище Python (глобальну інсталяцію Python).

Проблема¶

То в чому ж проблема встановлення пакетів у глобальне середовище Python?

З часом ви, вірогідно, писатимете багато різних програм, які залежать від різних пакетів. І деякі з цих ваших проєктів залежатимуть від різних версій одного й того ж пакета. 😱

Наприклад, ви можете створити проєкт із назвою philosophers-stone, ця програма залежить від іншого пакета з назвою harry, використовуючи версію 1. Тож вам потрібно встановити harry.

flowchart LR
    stone(philosophers-stone) -->|requires| harry-1[harry v1]

Потім, трохи згодом, ви створюєте інший проєкт із назвою prisoner-of-azkaban, і цей проєкт також залежить від harry, але йому потрібна версія harry 3.

flowchart LR
    azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]

Але тепер проблема в тому, що якщо ви встановлюєте пакети глобально (у глобальне середовище), а не у локальне віртуальне середовище, вам доведеться вибирати, яку версію harry встановити.

Якщо ви хочете запустити philosophers-stone, вам спочатку потрібно встановити harry версії 1, наприклад, так:

$ pip install "harry==1"

У підсумку у вас буде встановлено harry версії 1 у глобальному середовищі Python.

flowchart LR
    subgraph global[global env]
        harry-1[harry v1]
    end
    subgraph stone-project[philosophers-stone project]
        stone(philosophers-stone) -->|requires| harry-1
    end

Але якщо ви захочете запустити prisoner-of-azkaban, вам доведеться видалити harry версії 1 і встановити harry версії 3 (або просто встановлення версії 3 автоматично видалить версію 1).

$ pip install "harry==3"

У підсумку у вас буде встановлено harry версії 3 у глобальному середовищі Python.

А якщо ви знову спробуєте запустити philosophers-stone, є шанс, що він не працюватиме, тому що йому потрібен harry версії 1.

flowchart LR
    subgraph global[global env]
        harry-1[<strike>harry v1</strike>]
        style harry-1 fill:#ccc,stroke-dasharray: 5 5
        harry-3[harry v3]
    end
    subgraph stone-project[philosophers-stone project]
        stone(philosophers-stone) -.-x|⛔️| harry-1
    end
    subgraph azkaban-project[prisoner-of-azkaban project]
        azkaban(prisoner-of-azkaban) --> |requires| harry-3
    end

Порада

У пакетах Python дуже поширена практика намагатися якнайкраще уникати несумісних змін у нових версіях, але краще підстрахуватися та встановлювати новіші версії свідомо і тоді, коли ви можете запустити тести, щоб перевірити, що все працює коректно.

Тепер уявіть те саме з багатьма іншими пакетами, від яких залежать усі ваші проєкти. Це дуже складно керувати. І ви, імовірно, запускатимете деякі проєкти з деякими несумісними версіями пакетів і не розумітимете, чому щось не працює.

Також, залежно від вашої операційної системи (напр., Linux, Windows, macOS), у ній може бути вже встановлений Python. І в такому разі, імовірно, уже будуть попередньо встановлені деякі пакети з певними версіями, потрібними вашій системі. Якщо ви встановлюєте пакети в глобальне середовище Python, ви можете зламати деякі програми, що постачаються з вашою операційною системою.

Де встановлюються пакети¶

Коли ви встановлюєте Python, він створює на вашому комп'ютері кілька каталогів із деякими файлами.

Деякі з цих каталогів відповідають за зберігання всіх пакетів, які ви встановлюєте.

Коли ви запускаєте:

// Не запускайте це зараз, це лише приклад 🤓
$ pip install "fastapi[standard]"
---> 100%

Це завантажить стиснений файл з кодом FastAPI, зазвичай із PyPI.

Також будуть завантажені файли для інших пакетів, від яких залежить FastAPI.

Потім усе це буде розпаковано та покладено в каталог на вашому комп'ютері.

Типово ці завантажені та розпаковані файли будуть покладені в каталог, що постачається з вашою інсталяцією Python, це глобальне середовище.

Що таке віртуальні середовища¶

Рішенням проблеми з наявністю всіх пакетів у глобальному середовищі є використання віртуального середовища для кожного проєкту, над яким ви працюєте.

Віртуальне середовище - це каталог, дуже схожий на глобальний, у якому ви можете встановлювати пакети для конкретного проєкту.

Таким чином кожен проєкт матиме власне віртуальне середовище (каталог .venv) із власними пакетами.

flowchart TB
    subgraph stone-project[philosophers-stone project]
        stone(philosophers-stone) --->|requires| harry-1
        subgraph venv1[.venv]
            harry-1[harry v1]
        end
    end
    subgraph azkaban-project[prisoner-of-azkaban project]
        azkaban(prisoner-of-azkaban) --->|requires| harry-3
        subgraph venv2[.venv]
            harry-3[harry v3]
        end
    end
    stone-project ~~~ azkaban-project

Що означає активація віртуального середовища¶

Коли ви активуєте віртуальне середовище, наприклад так:

Linux, macOSWindows PowerShellWindows Bash

$ source .venv/bin/activate

$ .venv\Scripts\Activate.ps1

Або якщо ви використовуєте Bash для Windows (напр., Git Bash):

$ source .venv/Scripts/activate

Ця команда створить або змінить деякі Змінні оточення, які будуть доступні для наступних команд.

Однією з цих змінних є змінна PATH.

Порада

Ви можете дізнатися більше про змінну оточення PATH у розділі Змінні оточення.

Активація віртуального середовища додає його шлях .venv/bin (на Linux і macOS) або .venv\Scripts (на Windows) до змінної оточення PATH.

Скажімо, до активації середовища змінна PATH виглядала так:

Linux, macOSWindows

/usr/bin:/bin:/usr/sbin:/sbin

Це означає, що система шукатиме програми в:

/usr/bin
/bin
/usr/sbin
/sbin

C:\Windows\System32

Це означає, що система шукатиме програми в:

C:\Windows\System32

Після активації віртуального середовища змінна PATH виглядатиме приблизно так:

Linux, macOSWindows

/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin

Це означає, що система тепер спочатку шукатиме програми в:

/home/user/code/awesome-project/.venv/bin

перед тим, як шукати в інших каталогах.

Тож коли ви введете python у терміналі, система знайде програму Python у

/home/user/code/awesome-project/.venv/bin/python

і використає саме її.

C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32

Це означає, що система тепер спочатку шукатиме програми в:

C:\Users\user\code\awesome-project\.venv\Scripts

перед тим, як шукати в інших каталогах.

Тож коли ви введете python у терміналі, система знайде програму Python у

C:\Users\user\code\awesome-project\.venv\Scripts\python

і використає саме її.

Важлива деталь: шлях до віртуального середовища буде додано на початок змінної PATH. Система знайде його раніше за будь-який інший доступний Python. Таким чином, коли ви запускаєте python, використовується саме Python із віртуального середовища, а не будь-який інший python (наприклад, з глобального середовища).

Активація віртуального середовища також змінює ще кілька речей, але це одна з найважливіших.

Перевірка віртуального середовища¶

Коли ви перевіряєте, чи активне віртуальне середовище, наприклад так:

Linux, macOS, Windows BashWindows PowerShell

$ which python

/home/user/code/awesome-project/.venv/bin/python

$ Get-Command python

C:\Users\user\code\awesome-project\.venv\Scripts\python

Це означає, що програма python, яка буде використана, знаходиться у віртуальному середовищі.

На Linux і macOS використовують which, а в Windows PowerShell - Get-Command.

Принцип роботи цієї команди в тому, що вона перевіряє змінну оточення PATH, проходячи по кожному шляху по порядку, шукаючи програму з назвою python. Щойно вона її знайде, вона покаже вам шлях до цієї програми.

Найважливіше, що коли ви викликаєте python, це рівно той «python», який буде виконаний.

Отже, ви можете підтвердити, чи перебуваєте в правильному віртуальному середовищі.

Порада

Легко активувати одне віртуальне середовище, отримати один Python, а потім перейти до іншого проєкту.

І другий проєкт не працюватиме, бо ви використовуєте некоректний Python з віртуального середовища іншого проєкту.

Корисно вміти перевіряти, який саме python використовується. 🤓

Навіщо деактивувати віртуальне середовище¶

Наприклад, ви працюєте над проєктом philosophers-stone, активували його віртуальне середовище, встановили пакети та працюєте з цим середовищем.

А потім ви хочете працювати над іншим проєктом prisoner-of-azkaban.

Ви переходите до цього проєкту:

$ cd ~/code/prisoner-of-azkaban

Якщо ви не деактивуєте віртуальне середовище для philosophers-stone, коли ви запустите python у терміналі, він спробує використовувати Python із philosophers-stone.

$ cd ~/code/prisoner-of-azkaban

$ python main.py

// Помилка імпорту sirius, його не встановлено 😱
Traceback (most recent call last):
    File "main.py", line 1, in <module>
        import sirius

Але якщо ви деактивуєте віртуальне середовище і активуєте нове для prisoner-of-askaban, тоді при запуску python він використовуватиме Python із віртуального середовища в prisoner-of-azkaban.

$ cd ~/code/prisoner-of-azkaban

// Вам не потрібно бути в старому каталозі, щоб деактивувати, це можна зробити будь-де, навіть після переходу до іншого проєкту 😎
$ deactivate

// Активуйте віртуальне середовище в prisoner-of-azkaban/.venv 🚀
$ source .venv/bin/activate

// Тепер, коли ви запускаєте python, він знайде пакет sirius, встановлений у цьому віртуальному середовищі ✨
$ python main.py

I solemnly swear 🐺

Альтернативи¶

Це простий посібник, щоб ви швидко стартували та зрозуміли, як усе працює «під капотом».

Існує багато альтернатив керування віртуальними середовищами, залежностями пакетів (вимогами), проєктами.

Коли будете готові й захочете використовувати інструмент для керування всім проєктом, залежностями пакетів, віртуальними середовищами тощо, я раджу спробувати uv.

uv уміє багато чого, зокрема:

Встановлювати Python для вас, включно з різними версіями
Керувати віртуальним середовищем ваших проєктів
Встановлювати пакети
Керувати залежностями пакетів і версіями у вашому проєкті
Гарантувати, що у вас є точний набір пакетів і версій для встановлення, включно з їхніми залежностями, щоб ви були певні, що зможете запустити ваш проєкт у продакшені точно так само, як і на вашому комп'ютері під час розробки - це називається блокуванням
І багато іншого

Висновок¶

Якщо ви все це прочитали й зрозуміли, тепер ви знаєте значно більше про віртуальні середовища, ніж багато розробників. 🤓

Знання цих деталей, найімовірніше, стане в пригоді в майбутньому, коли ви налагоджуватимете щось, що виглядає складним, але ви знатимете, як усе працює «під капотом». 😎

Віртуальні середовища¶

Створіть проєкт¶

Створіть віртуальне середовище¶

Активуйте віртуальне середовище¶

Перевірте активність віртуального середовища¶

Оновіть pip¶

Додайте .gitignore¶

Встановіть пакети¶

Встановіть пакети безпосередньо¶

Встановіть з requirements.txt¶

Запустіть вашу програму¶

Налаштуйте ваш редактор¶

Деактивуйте віртуальне середовище¶

Готові до роботи¶

Навіщо віртуальні середовища¶

Проблема¶

Де встановлюються пакети¶

Що таке віртуальні середовища¶

Що означає активація віртуального середовища¶

Перевірка віртуального середовища¶

Навіщо деактивувати віртуальне середовище¶

Альтернативи¶

Висновок¶

Оновіть `pip`¶

Додайте `.gitignore`¶

Встановіть з `requirements.txt`¶