Skip to content

Руководство по работе с виртуальным окружением

Обзор

Проект использует виртуальное окружение Python для изоляции зависимостей. Виртуальное окружение создается в директории .venv/ и управляется через UV.

Создание виртуального окружения

Способ 1: Автоматический (рекомендуется)

Используйте скрипт автоматической настройки:

./scripts/setup/setup.sh

Скрипт автоматически: 1. Создаст виртуальное окружение (.venv/) 2. Установит все зависимости 3. Настроит pre-commit hooks

Способ 2: Ручной

# Создание виртуального окружения
uv venv

# Или через Makefile
make venv

Активация виртуального окружения

Linux/macOS

source .venv/bin/activate

Windows

.venv\Scripts\activate

Через скрипт

# Использование вспомогательного скрипта
source scripts/setup/activate_venv.sh

Проверка активации

После активации виртуального окружения:

  1. В начале строки терминала должно появиться (.venv)
  2. Проверка пути к Python: 
    which python  # Linux/macOS
where python  # Windows
# Должен показать путь к .venv/bin/python или .venv\Scripts\python.exe
  3. Проверка версии: 
    python --version  # Должен показать Python 3.10+

Работа в активированном окружении

После активации все команды можно выполнять напрямую без префикса uv run:

# Python скрипты
python script.py

# DVC команды
dvc repro
dvc status

# Тестирование
pytest
pytest --cov=src

# Форматирование и линтинг
black src tests
ruff check src tests
mypy src

# Pre-commit
pre-commit run --all-files

Деактивация окружения

deactivate

После деактивации префикс (.venv) исчезнет из строки терминала.

Установка зависимостей

В активированном окружении

# Установка всех зависимостей (включая dev зависимости)
uv sync --all-extras

# Добавление новой зависимости
uv add package-name

# Добавление dev зависимости
uv add --dev package-name

# Удаление зависимости
uv remove package-name

Без активации (через uv run)

# UV может работать и без явной активации
uv run python script.py
uv run pytest

Обновление зависимостей

# Обновление всех зависимостей до последних версий
uv sync --upgrade

# Обновление конкретной зависимости
uv add package-name@latest

Пересоздание окружения

Если нужно пересоздать виртуальное окружение:

# Удаление старого окружения
rm -rf .venv  # Linux/macOS
rmdir /s .venv  # Windows

# Создание нового
uv venv

# Активация и установка зависимостей
source .venv/bin/activate  # Linux/macOS
uv sync

Или используйте скрипт:

./scripts/setup/create_venv.sh

Структура виртуального окружения

.venv/
├── bin/          # Linux/macOS: исполняемые файлы (python, pip, etc.)
│   └── activate  # Скрипт активации
├── Scripts/      # Windows: исполняемые файлы
│   └── activate.bat  # Скрипт активации для Windows
├── lib/          # Установленные пакеты
└── pyvenv.cfg    # Конфигурация окружения

Исключение из Git

Виртуальное окружение .venv/ исключено из Git через .gitignore. Это правильная практика, так как: - Окружение можно пересоздать в любой момент - Оно содержит бинарные файлы, специфичные для платформы - Размер репозитория остается небольшим

Устранение проблем

Проблема: Команда uv venv не найдена

Решение: Установите UV: 

curl -LsSf https://astral.sh/uv/install.sh | sh
# или
pip install uv

Проблема: Окружение не активируется

Решение: Проверьте путь: 

ls -la .venv/bin/activate  # Linux/macOS
dir .venv\Scripts\activate.bat  # Windows

Проблема: Python не найден после активации

Решение: Пересоздайте окружение: 

rm -rf .venv
uv venv
source .venv/bin/activate

Проблема: Зависимости не устанавливаются

Решение: Убедитесь, что окружение активировано: 

which python  # Должен показать .venv/bin/python

Рекомендации

  1. Всегда активируйте окружение перед работой с проектом
  2. Используйте автоматическую настройку (./scripts/setup/setup.sh) для первого запуска
  3. Проверяйте активацию через which python или python --version
  4. Не коммитьте .venv/ в Git (уже настроено в .gitignore)
  5. Пересоздавайте окружение при проблемах с зависимостями

Дополнительные ресурсы