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

ЧерновикМатериалы дорабатываются и будут дополняться.

Автор: Антон Митьков

Настройка окружения

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

Окружение - набор установленных библиотек, их версий и настроек, в котором запускается код.

На этом курсе мы будем работать с ноутбуками .ipynb. Это специальные файлы, в которых код выполняется не весь целиком, а по ячейкам.

Обычный файл .py выполняется целиком: вы запускаете программу, и все строки идут подряд. Ноутбук .ipynb делится на ячейки. Каждую ячейку запускают отдельно (Shift+Enter), результат появляется сразу под ней, а переменные остаются в памяти для следующих ячеек. Поэтому в ноутбуках удобно пробовать идеи по шагам и смотреть промежуточные результаты.

После этого урока вы сможете открыть любой ноутбук .ipynb из учебника, выполнить в нём ячейки и установить нужные библиотеки. Для того, чтобы выполнять код ноутбуков, вам стоит выбрать способ работы с ними. Всего мы предлагаем 2 варианта:

В Google Colab с ноутбуками работают в браузере, а в VS Code — на своём компьютере.

Способ	Когда выбрать
Google Colab	Нужно начать за пять минут; компьютер слабый или нельзя ничего устанавливать.
VS Code на своём компьютере	Хочется работать без интернета, хранить файлы у себя и привыкнуть к инструментам разработчика.

Colab не требует установки. На своём компьютере нужны Python, виртуальная среда и VS Code. Инструмент выбирайте на своё усмотрение, но мы считаем, что Google Colab проще и быстрее погрузит вас в мир машинного обучения.

Вариант 1. Google Colab

Нужен аккаунт Google и браузер.

1. Скачайте ноутбук урока (.ipynb).
2. Откройте colab.research.google.com и войдите в аккаунт Google. Нажмите Upload notebook («Загрузить блокнот») или выберите File → Upload notebook.
3. В окне Open notebook на вкладке Upload нажмите Browse и укажите файл либо перетащите его в окно.

4. Нажмите Connect справа вверху. Colab выдаст временную виртуальную машину с Python и основными библиотеками.

5. Если урок использует файл с данными (.csv), откройте файловую панель слева (значок папки) и перетащите файл в неё. Панель покажет файлы, когда сеанс подключится.

6. Выполняйте ячейки сверху вниз. Чтобы запустить одну ячейку, используйте любой из способов:

   • нажать ▶ слева от ячейки;
   • Shift + Enter — выполнить ячейку и перейти к следующей;
   • Ctrl + Enter (на Mac Cmd + Enter) — выполнить ячейку и остаться в ней;
   • Alt + Enter (на Mac Option + Enter) — выполнить ячейку и добавить новую ниже.

   Чтобы запустить весь ноутбук, выберите Runtime → Run all («Среда выполнения» → «Выполнить всё»).

Интерфейс Colab англоязычный или русскоязычный в зависимости от настроек аккаунта; названия пунктов совпадают по смыслу. Чтобы скачать ноутбук на компьютер как файл .ipynb, выберите File → Download. Сохранить изменения в Google Drive можно отдельной командой File → Save (Ctrl/Cmd + S).

Что важно знать:

• Файлы и установленные библиотеки пропадают, когда сеанс заканчивается. Скачайте результат на компьютер: File → Download → Download .ipynb, либо сохраните в Google Drive: File → Save.
• Colab уже содержит NumPy, pandas, matplotlib, scikit-learn и PyTorch. Если версия нужна точно как в учебнике, загрузите requirements.txt в файловую панель и выполните в отдельной ячейке:

%pip install -r requirements.txt

• После установки при запросе выберите Runtime → Restart session. Это перезапустит ядро Python, установленные библиотеки останутся. В Colab нет пункта «Restart Kernel»: так называется эта команда в VS Code.

Вариант 2. VS Code на своём компьютере

Как устроена среда

Нам нужны три вещи:

1. Python 3.14 — интерпретатор, который выполняет код.
2. Виртуальная среда .venv — папка внутри проекта с собственным Python и библиотеками. Она не затрагивает системный Python, а разные проекты не мешают друг другу.
3. VS Code с расширениями Python и Jupyter — редактор, в котором открываются ноутбуки.

Установка Python и VS Code зависит от системы, поэтому сначала выполните раздел для своей ОС. Затем переходите к общим шагам 3–6: они одинаковы везде.

macOS

1. Откройте Терминал (Cmd+Пробел, «Terminal») и проверьте Python:

   python3 --version
   

   Нужна версия 3.14. Если версия ниже или команды нет, установите Python с python.org/downloads (файл .pkg) или через Homebrew (если он не установлен, установите его по инструкции на сайте):

   brew install python@3.14
   

2. Установите VS Code с code.visualstudio.com: скачайте архив, распакуйте и перетащите приложение в «Программы».

Дальше переходите к общим шагам.

Linux

Команды даны для Ubuntu/Debian; в других дистрибутивах названия пакетов отличаются.

1. Проверьте Python и установите модуль для виртуальных сред:

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

   Если в вашем дистрибутиве версия ниже 3.14, установите Python через uv: uv python install 3.14. Среду тогда создавайте командой uv venv --python 3.14.

2. Установите VS Code: скачайте пакет .deb с code.visualstudio.com и выполните

   sudo apt install ./имя-файла.deb
   

   Либо установите через Snap: sudo snap install code --classic.

Дальше переходите к общим шагам.

Windows

На Windows Python иногда устанавливается с трудностями. Если что-то пошло не так, следуйте официальной инструкции Python для Windows и руководству VS Code по Python.

1. Скачайте установщик Python с python.org/downloads. На первом экране установщика поставьте галочку «Add python.exe to PATH», затем нажмите «Install Now».
2. Установите VS Code с code.visualstudio.com (VSCodeUserSetup). Все параметры можно оставить по умолчанию.

Откройте PowerShell и проверьте Python:

python --version

Если видите ошибку или открывается Microsoft Store, перезапустите PowerShell. Если не помогло, см. раздел «Если не получилось» или официальную инструкцию выше.

В Windows используйте python вместо python3, а среду активируйте командой .venv\Scripts\Activate.ps1. Если PowerShell запрещает запуск скриптов, выполните один раз:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Дальше переходите к общим шагам.

Общие шаги для VS Code

Шаг 3. Создайте папку проекта и откройте её. Создайте папку, например ml-handbook, положите в неё ноутбук, файлы данных урока и requirements.txt. В VS Code выберите File → Open Folder и укажите эту папку.

Шаг 4. Установите расширения. Нажмите значок расширений слева (или Ctrl+Shift+X / Cmd+Shift+X), найдите и установите Python и Jupyter (оба от Microsoft).

Значок расширений обведён в левой панели. Если расширение ещё не установлено, вместо Disable и Uninstall будет кнопка Install. Так же устанавливается расширение Python.

Шаг 5. Создайте виртуальную среду и установите библиотеки. Откройте терминал в VS Code: Terminal → New Terminal (Ctrl+`). Выполните команды для вашей системы.

Вкладка Terminal находится на нижней панели; в строке терминала вводят команды. Обозначение (.venv) в начале строки означает, что среда активна.

Если панели нет, откройте её через меню Terminal → New Terminal или сочетанием Ctrl+` (на macOS тоже Ctrl, не Cmd). Строка «Executing task» вверху появилась из-за способа съёмки; у вас её не будет.

macOS и Linux:

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

Windows (PowerShell):

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install jupyter ipykernel -r requirements.txt

В начале строки терминала появится (.venv) — среда активна. Установка занимает несколько минут: PyTorch весит больше гигабайта; он нужен только для уроков про нейросети, поэтому при нехватке места или времени его можно не устанавливать: удалите строку torch из requirements.txt и поставьте его позже.

Шаг 6. Откройте ноутбук и выберите ядро. Дважды щёлкните по .ipynb в проводнике. Справа вверху нажмите Select Kernel → Python Environments и выберите .venv. Если среды нет в списке, нажмите Ctrl+Shift+P (Cmd+Shift+P), выполните Python: Select Interpreter и укажите .venv.

Кнопка Select Kernel открывает список сред. Рядом с ячейкой расположена кнопка её запуска, а в проводнике видна папка .venv.

Чтобы запустить одну ячейку, используйте любой из способов:

• нажать ▶ слева от ячейки;
• Shift + Enter — выполнить ячейку и перейти к следующей;
• Ctrl + Enter (на Mac Cmd + Enter) — выполнить ячейку и остаться в ней;
• Alt + Enter (на Mac Option + Enter) — выполнить ячейку и добавить новую ниже.

Чтобы запустить весь ноутбук, нажмите Run All на панели над ячейками. Для чистой проверки сначала нажмите Restart, затем Run All.

Проверка

Скачайте тестовый ноутбук environment-check.ipynb и откройте его тем способом, который вы выбрали (в Colab через Upload notebook, в VS Code через File → Open). Выполняйте ячейки сверху вниз: Shift+Enter.

Ноутбук проверяет по порядку: версию Python, установленные библиотеки, NumPy и pandas, построение графика, обучение маленькой модели и PyTorch. Среда настроена, если в конце вывод «Всё работает: среда готова.» (или «Основная среда готова» с напоминанием про PyTorch, см. ниже) и нет красных ошибок. В Colab версии могут отличаться от requirements.txt: для уроков учебника это допустимо.

Если напротив названия библиотеки в выводе написано «НЕ УСТАНОВЛЕНА», установите её по инструкции выше и перезапустите ядро. В VS Code это кнопка Restart (команда Restart Kernel) на панели над ячейками, в Colab Runtime → Restart session. Если ошибка другая, найдите её в таблице ниже.

Если не получилось

Ниже таблица с типичными ошибками. Для двух проблем в Windows после таблицы есть подробные разборы, они скрыты: нажмите на строку «Подробный разбор», чтобы раскрыть решение.

Проблема	Что сделать
python: command not found (macOS, Linux)	Используйте python3. После активации среды работает python.
Windows: python открывает Microsoft Store	Python не найден в PATH. См. подробный разбор.
Activate.ps1 cannot be loaded	PowerShell запретил запуск скриптов. См. подробный разбор.
ModuleNotFoundError: No module named 'numpy'	Ядро выбрано не из .venv: выберите его заново (шаг 6) или установите библиотеки в активированной среде.
externally-managed-environment (Linux)	Вы ставите библиотеки в системный Python. Сначала создайте и активируйте .venv.
Нет venv в Linux	sudo apt install python3-venv.
Ядра .venv нет в списке	Перезапустите VS Code; убедитесь, что установлен ipykernel.
Нет места или долгая установка PyTorch	PyTorch необязателен на старте: уберите строку torch из requirements.txt и поставьте его позже или используйте Colab.

Windows: команда python открывает Microsoft Store

Windows не нашёл установленный Python и предлагает скачать его из магазина. Если разбор ниже не помог, воспользуйтесь официальной инструкцией Python для Windows. Либо Python не установлен, либо при установке не поставили галочку «Add python.exe to PATH».

Подробный разбор: Python не найден в Windows

1. Закройте все окна PowerShell и VS Code.
2. Нажмите Win, начните вводить «Параметры» и откройте Параметры → Приложения → Установленные приложения. Найдите в списке Python 3.14. Если его нет, переходите к шагу 5.
3. Нажмите «⋯» рядом с Python и выберите Изменить. В окне установщика нажмите Modify, затем Next. В окне Advanced Options поставьте галочку Add Python to environment variables и нажмите Install. Если такого окна нет, выберите Repair и после него вернитесь к этому шагу.
4. Откройте PowerShell заново и выполните python --version. Должно вывести Python 3.14.x.
5. Если Python не установлен: скачайте установщик с python.org/downloads/windows, запустите его и на первом экране поставьте галочку Add python.exe to PATH. Только после этого нажмите Install Now.
6. Если python --version всё равно открывает Store: Параметры → Приложения → Дополнительные параметры → Псевдонимы выполнения приложений (App execution aliases). Выключите переключатели у python.exe и python3.exe (App Installer). Перезапустите PowerShell.

Windows: PowerShell запрещает запуск скриптов

Полный текст ошибки: Activate.ps1 cannot be loaded because running scripts is disabled on this system.

Команда .venv\Scripts\Activate.ps1 запускает скрипт, а PowerShell по умолчанию запрещает запуск скриптов. Нужно один раз разрешить скрипты для вашего пользователя.

Подробный разбор: разрешить скрипты в PowerShell

1. В PowerShell выполните команду:

   Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
   

2. PowerShell спросит подтверждение. Введите Y и нажмите Enter. Права администратора не нужны: изменение касается только вашего пользователя.

3. Закройте терминал в VS Code и откройте новый: Terminal → New Terminal.

4. Снова выполните .venv\Scripts\Activate.ps1. В начале строки должно появиться (.venv).

5. Если сообщение осталось, проверьте политику командой Get-ExecutionPolicy -List. В строке CurrentUser должно быть RemoteSigned.

6. Запасной вариант без изменения политики: в терминале VS Code выберите профиль Command Prompt (стрелка рядом с «+» → Command Prompt) и активируйте среду командой .venv\Scripts\activate.bat.

Самопроверка

• Вы можете запустить ячейку и увидеть вывод.
• Проверочная ячейка выводит версии библиотек без ошибок.
• Вы знаете, где лежит ноутбук и как его сохранить (в Colab — скачать .ipynb).
• Вы отличаете системный Python от Python внутри .venv.

Теперь можно переходить к следующим урокам. Если среда не заработала, вернитесь к таблице проблем или запустите ноутбук в Colab.

Файлы

• Проверка среды (.ipynb) · Открыть в браузере
• Библиотеки для примеров