Виртуальная среда

При работе с проектами в Python рекомендуется использовать виртуальную среду разработки (или какой-нибудь другой подобный механизм). Это нужно для того, чтобы изолировать устанавливаемые пакеты для каждого отдельного проекта.

Дополнительная информация

Если вы уже знакомы с виртуальными средами разработки, знаете как их создавать и использовать, то вы можете свободно пропустить данный раздел. 🤓

Подсказка

Виртуальная среда и переменная окружения это две разные вещи.

Переменная окружения это системная переменная, которую могут использовать программы.

Виртуальная среда это папка, содержащая файлы.

Дополнительная информация

В этом разделе мы научим вас пользоваться виртуальными средами разработки и расскажем, как они работают.

Если же вы готовы воспользоваться инструментом, который умеет управлять всем, что касается Python-проектов, (включая установку Python), то попробуйте uv.

Создание проекта

В первую очередь, создайте директорию для вашего проекта.

Я обычно создаю папку под названием code внутри моего домашнего каталога /home/user.

Затем внутри данной папки я создаю отдельную директорию под каждый свой проект.

// Перейдите в домашний каталог
$ cd
// Создайте отдельную папку под все будущие программные проекты (code)
$ mkdir code
// Войдите в директорию code
$ cd code
// Создайте директрорию под данный проект (awesome-project)
$ 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

Проверка активации виртуальной среды

Проверьте, активна ли виртуальная среда (удостоверимся, что предыдущая команда сработала).

Подсказка

Убедитесь в том, что все работает так, как нужно и вы используете именно ту виртуальную среду разработки, которую нужно. Делать это необязательно, но желательно.

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 до последней версии.

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

Подсказка

Обычно это делается только один раз, сразу после создания виртуальной среды разработки.

Убедитесь в том, что виртуальная среда активирована (с помощью вышеуказанной команды) и запустите следующую команду:

$ python -m pip install --upgrade pip

---> 100%

Добавление .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

Настройка редактора

Вероятно, вы захотите воспользоваться редактором. Убедитесь, что вы настроили его на использование той самой виртуальной среды, которую вы создали. (Скорее всего, она автоматически будет обнаружена). Это позволит вам использовать авто-завершение и выделение ошибок в редакторе.

Например:

• VS Code
• PyCharm

Подсказка

Обычно это делается один раз, при создании виртуальной среды разработки.

Деактивация виртуальной среды разработки

По окончании работы над проектом вы можете деактивировать виртуальную среду.

$ deactivate

Таким образом, при запуске python, будет использована версия 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"

И тогда в вашем глобальном окружении Python будет установлен harry версии 1:

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, пакет версии 1 удаляется автоматически).

$ pip install "harry==3"

И тогда, в вашей глобальной среде окружения Python, будет установлен пакет harry версии 3.

И когда вы снова попытаетесь запустить 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, то на вашей машине создается некоторое количество директорий, содержащих некоторое количество файлов.

Среди них есть каталоги, отвечающие за хранение всех устанавливаемых вами пакетов.

Когда вы запустите команду:

// Не запускайте эту команду, это просто пример 🤓
$ 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 из виртуальной среды разработки.

Вы используете which для Linux и macOS и Get-Command для Windows PowerShell.

Эта команда работает следующим образом: она проверяет переменную окружения 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

// Error importing sirius, it's not installed 😱
Traceback (most recent call last):
    File "main.py", line 1, in <module>
        import sirius

Но если вы деактивируете виртуальную среду разработки и активируете новую среду для prisoner-of-askaban, то вы тогда запустите Python из виртуального окружения prisoner-of-azkaban.

$ cd ~/code/prisoner-of-azkaban

// Вам не требуется находится в старой директории для деактивации среды разработки, вы можете это сделать откуда угодно, даже из каталога другого проекта, в который вы перешли. 😎
$ deactivate

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

// Тепреь, когда вы запустите python, он найдет пакет sirius, установленный в виртуальной среде ✨
$ python main.py

Я торжественно клянусь в этом! 🐺

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

Это простое руководство поможет вам начать работу и научит тому, как всё работает изнутри.

Существует много альтернативных решений для работы с виртуальными средами разработки, с программными зависимостями, а также с проектами.

Когда вы будете готовы использовать единый инструмент для управления проектом, программными зависимостями, виртуальными средами разработки и т.д., то я рекомендую вам попробовать uv.

uv может очень многое. Он умеет:

• Устанавливать Python, включая установку различных версий
• Управлять средой виртуального окружения вашего проекта
• Устанавливать пакеты
• Управлять пакетами и их версиями внутри вашего проекта
• Удостовериться, что вы используете точный набор пакетов и версий при установке, включая зависимости. Таким образом, вы можете быть уверенны, что проект, запускается в production, точно также, как и при разработке, этот механизм называется locking
• Многие другие вещи

Заключение

Если вы прочитали и поняли всё это, то теперь вы знаете гораздо больше о виртуальных средах разработки, чем многие другие разработчики. 🤓

Скорее всего, знание этих деталей будет полезно вам в будущем. Когда вы будете отлаживать что-то, кажущееся сложным, вы будете знать, как это работает под капотом. 😎