From:To:
11¶ ## Зачем это всё
22
33 Настроенный редактор экономит больше времени, чем любой приём программирования: он подсвечивает опечатку **до** запуска, показывает тип под курсором и форматирует файл сам.
44
55 Это не подготовка к работе — это уже работа. В MIT есть отдельный курс [The Missing Semester of Your CS Education](https://missing.csail.mit.edu/), созданный ровно потому, что программы учат алгоритмам, но не инструментам, хотя за инструментами человек проводит сотни часов за учёбу и тысячи за карьеру.
66
77 Порядок шагов важен: сначала редактор, потом инструменты, потом проверка каждого по отдельности. Если проверять всё разом в конце, непонятно, что именно не встало.
88
99 ---
1010
11− **Список работает и на Windows, и на macOS.** В поле команды у каждого шага — вариант для Windows, а в описании рядом всегда есть команда для macOS и прямая ссылка на официальную страницу загрузки — на случай, если пакетный менеджер не работает.
11+ **Список работает и на Windows, и на macOS.** В поле команды — вариант для Windows, в описании рядом — команда для macOS. Ссылки на официальные страницы загрузки прикреплены к шагам — на случай, если пакетный менеджер не работает.
1212## Подготовка
13131. Пакетный менеджер [recommended]
1414 **Windows:** ничего делать не надо — `winget` встроен в систему. Проверь командой ниже.
1515
16− **macOS:** поставь Homebrew — **[brew.sh](https://brew.sh/)**. Команда установки есть на главной странице. После установки он напечатает две строки, которые надо выполнить, чтобы `brew` попал в PATH — не пропусти их, это самая частая ошибка. Проверяется командой `brew --version`.
16+ **macOS:** поставь Homebrew — команда установки есть на главной странице. После установки он напечатает две строки, которые надо выполнить, чтобы `brew` попал в PATH — не пропусти их, это самая частая ошибка. Проверяется командой `brew --version`.
1717 $ winget --version
1818 why: Пакетный менеджер ставит программы одной командой и потом обновляет их все разом. Главное — такую установку можно записать и повторить на другой машине, а «скачать и кликнуть далее» — нельзя.
1919 - [ ] Команда пакетного менеджера твоей системы отвечает версией
2020 - [ ] На macOS: выполнены строки про PATH, которые напечатал установщик
21+ → Homebrew — установка (macOS) — https://brew.sh/
2122## Редактор
22232. Установить VS Code
23− Скачать вручную: **[code.visualstudio.com/download](https://code.visualstudio.com/download)**
24−
2524 **Windows:** команда ниже. При установке вручную отметь галочку «Add to PATH».
2625
27− **macOS:** `brew install --cask visual-studio-code`. Если ставишь вручную — перетащи приложение в папку Applications, иначе часть функций работать не будет. Инструкция: **[настройка VS Code на macOS](https://code.visualstudio.com/docs/setup/mac)**
26+ **macOS:** `brew install --cask visual-studio-code`. Если ставишь вручную — перетащи приложение в папку Applications, иначе часть функций работать не будет.
2827 $ winget install Microsoft.VisualStudioCode
2928 why: VS Code — редактор, который становится полноценной средой разработки за счёт расширений. В отличие от тяжёлой IDE, ты сам решаешь, что в нём будет.
3029 - [ ] VS Code запускается
3130 - [ ] В окне «About» видна версия редактора
31+ → Скачать VS Code — https://code.visualstudio.com/download
32+ → Настройка на macOS — https://code.visualstudio.com/docs/setup/mac
32333. Проверить, что команда code доступна в терминале
3334 Открой **новый** терминал — старый не знает об изменении PATH.
3435
3536 **Если команда не найдена на Windows:** переустанови с галочкой «Add to PATH».
3637
3738 **Если на macOS:** открой VS Code, нажми Cmd+Shift+P и выполни команду «Shell Command: Install 'code' command in PATH».
3839 $ code --version
3940 why: Дальше мы будем ставить расширения командами. Без code в PATH придётся кликать мышью по магазину расширений, а такую настройку невозможно повторить на другой машине.
4041 - [ ] Команда напечатала три строки: версию, хеш коммита и архитектуру
4142 - [ ] Терминал был открыт заново после установки
4243## Расширения
43444. Поставить расширение Python
44− Страница расширения: **[Python на Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-python.python)**
45−
4645 Команда одинаковая на Windows и macOS.
4746
4847 Расширение даёт подсветку, переход к определению, запуск и отладку. Вместе с ним автоматически приезжает Pylance — проверка типов и автодополнение.
4948 $ code --install-extension ms-python.python
5049 why: Pylance находит ошибки статически: обращение к несуществующему атрибуту или неверный тип аргумента видно до запуска. Это дешевле, чем ловить то же самое, гоняя программу.
5150 - [ ] В панели Extensions расширение Python отмечено как установленное
5251 - [ ] Там же появился Pylance — он ставится как зависимость, отдельно его ставить не надо
52+ → Python на Marketplace — https://marketplace.visualstudio.com/items?itemName=ms-python.python
53535. Поставить Ruff
54− Страница расширения: **[Ruff на Marketplace](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)**
55−
5654 Команда одинаковая на обеих системах.
5755
5856 Линтер и форматтер в одном инструменте. Тот же самый, который будет проверять код в проекте, — важно, чтобы редактор и проект ругались одинаково.
5957 $ code --install-extension charliermarsh.ruff
6058 why: Форматтер отвечает за единообразие (отступы, кавычки, переносы), линтер — за подозрительные места (неиспользуемая переменная, затенение имени). Разные задачи, но здесь один инструмент.
6159 - [ ] Ruff виден в списке установленных расширений
60+ → Ruff на Marketplace — https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
61+ → Документация Ruff — https://docs.astral.sh/ruff/
62626. Поставить Docker и GitLens [recommended]
63− Страницы расширений: **[Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker)** и **[GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)**
64−
6563 Команда одинаковая на обеих системах.
6664
6765 Docker покажет контейнеры и их логи прямо в редакторе. GitLens показывает, кто и когда менял конкретную строку.
6866 $ code --install-extension ms-azuretools.vscode-docker --install-extension eamodio.gitlens
6967 why: Оба нужны не сразу, но ставятся один раз. GitLens особенно полезен, когда начнёшь разбираться в чужом коде: строка перестаёт быть безымянной.
7068 - [ ] Оба расширения в списке установленных
69+ → Docker на Marketplace — https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker
70+ → GitLens на Marketplace — https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens
7171¶ **Почему ставим по одному, а не пакетом «всё для Python».**
7272
7373 Каждое расширение — работающий процесс и потенциальный источник конфликта: два форматтера начнут переписывать файл друг за другом, и ты будешь гадать, почему код прыгает при сохранении.
7474
7575 Ставя по одному, ты знаешь, кто за что отвечает, и понимаешь, что отключать при странном поведении.
7676## Терминал
77777. Открыть встроенный терминал
7878 **Windows:** Ctrl + ` (клавиша с обратным апострофом, слева от единицы).
7979
8080 **macOS:** Ctrl + ` (именно Control, не Command).
8181
8282 Либо меню View → Terminal на обеих системах.
8383 why: Отдельное окно консоли — лишнее переключение и лишний шанс запустить команду не в той папке. Встроенный терминал открывается сразу в папке проекта.
8484 - [ ] Терминал открылся в нижней части окна редактора
8585 - [ ] В нём виден путь к текущей папке
86868. Понять, какая оболочка запущена
8787 В правом верхнем углу панели терминала написано имя оболочки. Запомни его.
8888
8989 **Windows:** обычно PowerShell, реже Command Prompt или Git Bash.
9090
9191 **macOS:** по умолчанию zsh. Проверить можно командой `echo $SHELL`.
9292 why: Оболочки ведут себя по-разному: разный синтаксис переменных, разные кавычки, разные разделители в путях. zsh и bash близки, а PowerShell отличается сильно: команды из статей чаще всего написаны под bash и в нём не работают. Половина загадочных ошибок новичка — это команда не из той оболочки.
9393 - [ ] Ты можешь назвать, какая оболочка у тебя запущена
9494 - [ ] Понимаешь, что команды из интернета могут быть написаны под другую
9595## Инструменты
96969. Проверить Python
97− Скачать: **[python.org/downloads](https://www.python.org/downloads/)** · страница для macOS: **[python.org/downloads/macos](https://www.python.org/downloads/macos/)**
98−
9997 Нужна версия 3.12 или новее.
10098
10199 **Windows:** команда `python --version`. Ставь с python.org, не из Microsoft Store. При установке отметь «Add python.exe to PATH».
102100
103101 **macOS:** команда `python3 --version` — именно python3. Системный Python старый и трогать его нельзя — ставь свой: `brew install python@3.12` либо позже через `uv python install 3.12`.
104102 $ python --version
105− why: На Windows версия из Microsoft Store работает в песочнице: часть инструментов её не находит. На macOS опасность другая: системный Python используется самой системой, и установка в него пакетов может сломать системные утилиты. Поэтому в обоих случаях нужен свой интерпретатор.
103+ why: На Windows версия из Microsoft Store работает в песочнице: часть инструментов её не находит. На macOS опасность другая: системный Python используется самой системой, и установка в него пакетов может сломать системные утилиты.
106104 - [ ] Команда напечатала версию 3.12 или выше
107105 - [ ] Это не системный Python и не версия из Microsoft Store
106+ → Скачать Python — https://www.python.org/downloads/
107+ → Python для macOS — https://www.python.org/downloads/macos/
10810810. Убедиться, что запускается именно тот Python
109109 Команда покажет все найденные интерпретаторы в порядке приоритета. Первый в списке — тот, который запустится.
110110
111111 **Windows:** `where python`
112112
113113 **macOS:** `which -a python3`
114114 $ where python
115115 why: На машине часто оказывается несколько Python: системный, от пакетного менеджера, из старой установки. Запускается первый по PATH, и пакет, поставленный в одно окружение, «пропадает» при запуске из другого. Это одна из самых частых и самых непонятных проблем новичка.
116116 - [ ] Ты видишь список найденных интерпретаторов
117117 - [ ] Понимаешь, какой из них запускается по умолчанию
11811811. Проверить git
119− Скачать: **[git-scm.com/downloads](https://git-scm.com/downloads)** · страница для macOS: **[git-scm.com/download/mac](https://git-scm.com/download/mac)**
120−
121119 **Windows:** при установке можно оставить настройки по умолчанию — вместе с git приедет Git Bash.
122120
123121 **macOS:** проще всего `xcode-select --install` — git входит в Command Line Tools. Либо свежее версией: `brew install git`.
124122 $ git --version
125123 why: Git — не «сохранялка файлов», а машина времени. Без него любая попытка что-то поменять сопровождается страхом сломать работающее; с ним эксперимент бесплатен.
126124 - [ ] Команда напечатала версию git
125+ → Скачать git — https://git-scm.com/downloads
126+ → git для macOS — https://git-scm.com/download/mac
12712712. Проверить Docker
128− Скачать: **[Docker Desktop](https://www.docker.com/products/docker-desktop/)** · через Homebrew: **[cask docker-desktop](https://formulae.brew.sh/cask/docker-desktop)**
129−
130128 **Windows:** скачать с сайта или `winget install Docker.DockerDesktop`.
131129
132130 **macOS:** `brew install --cask docker-desktop`. При ручной загрузке выбери правильную сборку: **Apple Silicon** для M1–M4 или **Intel** для старых машин. Посмотреть свой процессор: ⌘ → «Об этом Mac».
133131
134132 На обеих системах Docker должен быть не просто установлен, а **ЗАПУЩЕН** — значок кита в трее или в верхней панели.
135133 $ docker run --rm hello-world
136134 why: Типичная ловушка: Docker установлен, но не запущен, и команды падают с невнятной ошибкой про подключение к демону. Проверять надо не наличие программы, а её работу.
137135 - [ ] Команда скачала образ и напечатала приветствие
138136 - [ ] Значок Docker активен, а не серый
139137 - [ ] На macOS: скачана сборка под свой процессор
138+ → Скачать Docker Desktop — https://www.docker.com/products/docker-desktop/
139+ → Через Homebrew (macOS) — https://formulae.brew.sh/cask/docker-desktop
14014013. Установить uv
141− Инструкция для всех систем: **[docs.astral.sh/uv — установка](https://docs.astral.sh/uv/getting-started/installation/)**
142−
143141 **Windows:** `winget install astral-sh.uv`
144142
145143 **macOS:** `brew install uv` либо официальный установщик: `curl -LsSf https://astral.sh/uv/install.sh | sh`
146144
147145 После установки закрой терминал и открой заново.
148146 $ winget install astral-sh.uv
149147 why: uv — единый инструмент: ставит сам Python, управляет зависимостями, запускает команды проекта. Заменяет связку из нескольких и работает на порядок быстрее. Дальше весь проект будет жить через него.
150148 - [ ] Установка завершилась без ошибок
151149 - [ ] Терминал открыт заново после установки
150+ → Установка uv — все системы — https://docs.astral.sh/uv/getting-started/installation/
151+ → Документация uv — https://docs.astral.sh/uv/
15215214. Проверить uv
153153 Команда одинаковая на обеих системах.
154154
155155 Если команда не найдена — терминал ещё помнит старый PATH. Закрой все терминалы и открой новый. На macOS при установке через скрипт проверь, что в PATH добавился `~/.local/bin`.
156156 $ uv --version
157157 why: Это последняя проверка перед созданием проекта. Дальше все команды пойдут через uv, и его недоступность остановит работу на первом же шаге.
158158 - [ ] Команда напечатала версию uv
159159## Проект
16016015. Создать папку проекта по короткому пути
161161 Никаких пробелов, никакой кириллицы, не на Рабочем столе и не в облачной папке.
162162
163163 **Windows:** `mkdir C:\dev\shop` — не в OneDrive.
164164
165165 **macOS:** `mkdir -p ~/dev/shop` — не в iCloud Drive и не в папке «Документы», если у тебя включена синхронизация Рабочего стола и Документов.
166166 $ mkdir C:\dev\shop
167167 why: Многие инструменты разбирают путь по пробелам как разделителям аргументов — путь распадается на части. С кириллицей проблема в кодировке. Ошибка выглядит не как «плохой путь», а как «файл не найден», и ищут её долго. Облачная синхронизация добавляет своё: она конфликтует с файлами, которые часто меняются.
168168 - [ ] В полном пути к папке нет пробелов
169169 - [ ] В полном пути нет кириллических символов
170170 - [ ] Папка не в облачном хранилище и не на Рабочем столе
17117116. Открыть папку в VS Code
172172 File → Open Folder, либо командой из терминала.
173173
174174 **Windows:** `code C:\dev\shop`
175175
176176 **macOS:** `code ~/dev/shop`
177177 $ code C:\dev\shop
178178 why: VS Code работает именно с папкой, а не с отдельными файлами: от неё он отсчитывает пути, ищет настройки и запускает терминал. Открытый «просто файл» лишает тебя половины возможностей редактора.
179179 - [ ] В боковой панели видно имя папки проекта
180180 - [ ] Встроенный терминал открывается сразу в этой папке
18118117. Включить форматирование при сохранении
182182 **Windows:** Ctrl+Shift+P → «Preferences: Open Workspace Settings (JSON)»
183183
184184 **macOS:** Cmd+Shift+P → та же команда
185185
186186 Добавь настройку editor.formatOnSave со значением true и назначь Ruff форматтером для Python.
187187 why: Спор об оформлении кода — самый бессмысленный из возможных. Когда формат ставит инструмент, спорить не о чем, а в pull request видны только смысловые изменения, а не переставленные пробелы.
188188 - [ ] Файл .vscode/settings.json создан в папке проекта
189189 - [ ] editor.formatOnSave включён
190+ → Настройки VS Code — https://code.visualstudio.com/docs/getstarted/settings
19019118. Проверить, что форматирование работает
191192 Создай файл check.py, напиши в нём строку с намеренно кривыми отступами и лишними пробелами, сохрани. Оформление должно поправиться само. После проверки файл удали.
192193 why: Настройка, которую не проверили, считается неработающей. Это правило пригодится дальше во всём: конфиг без проверки — это предположение, а не факт.
193194 - [ ] После сохранения оформление файла изменилось само
194195 - [ ] Проверочный файл удалён
195196¶
196197¶
197198¶
198199¶ ## Готово
199200
200201 Если все проверки пройдены — рабочее место настроено, и дальше можно заниматься кодом, а не выяснять, почему команда не находится.
201202
202203 **Что дальше:** git и GitHub — ключи, клонирование, первая ветка. А затем первый pull request целиком, на безобидной правке README, чтобы к моменту появления настоящего кода механика уже была в руках.
203204
204205 Если какой-то шаг не сошёлся — не переходи дальше. Незакрытая проблема в окружении не рассасывается, а всплывает через две недели в самый неудобный момент.