Machine Learning for Trading / Installation
Machine Learning for Trading 安装：Docker、WSL2 与本地 uv
官方提供两条主线：Docker（推荐，自带环境无需编译依赖）与本地 uv（macOS/Linux/WSL2）。Windows 用户必须走 WSL2，PowerShell 直装不受支持——scikit-learn 在当前 Python 版本没有 Windows wheel，源码编译会失败。
三种安装路径对照
以下路径与前置来自官方 README（2026-08 核验）。
| 路径 | 适用平台 | 前置 | 特点 |
|---|---|---|---|
| Docker（Option A） | Linux / Windows WSL2 / macOS | Docker Desktop / docker compose | 推荐；环境自带，无需 C/C++ 编译器与 Python headers |
| WSL2 + uv（Option B） | Windows | WSL2（Ubuntu）+ uv + build-essential + python3-dev | Windows 唯一可用路径；scikit-learn 需源码编译 |
| 本地 uv（Option B） | macOS（Apple Silicon）/ Linux / WSL2 | uv + Xcode CLT（macOS）或 build-essential（Linux） | Intel Mac 不可用（PyTorch 无 x86_64 wheel），仅 Docker |
Docker 快速安装步骤
官方推荐的 Docker 路径最省心，从仓库根目录执行。
克隆仓库
git clone https://github.com/stefan-jansen/machine-learning-for-trading.git && cd machine-learning-for-trading
准备环境变量
cp .env.example .env，按需填入数据源 API key（免费数据集无需 key）。
拉取镜像并启动
docker compose pull ml4t，然后 docker compose up -d ml4t 启动 Jupyter Lab。
下载免费数据
在 Jupyter Lab 终端执行 python data/download_all.py --free-only（约 4 GB / 12 分钟）。
跑第一个 notebook
从 01_process_is_edge 章节开始，或直接进入 9 个 case_studies。
5 个 Docker 镜像：按需选择
多数 notebook 用默认 ml4t 镜像；少数需要专用镜像，各 notebook 前言会注明。以下是完整镜像清单（来自官方 README）。
| 镜像 | 覆盖范围 | 何时需要 |
|---|---|---|
| ml4t | 全部 27 章 + 9 案例（CPU） | 默认，绝大多数场景 |
| ml4t-gpu | 同 ml4t，用 NVIDIA runtime（--profile gpu） | 深度学习章节 |
| ml4t-py312 | Python 3.12（signatory/esig/gensim/tfcausalimpact） | 约 10 个 notebook |
| benchmark | 数据库客户端（TimescaleDB/ClickHouse/QuestDB/InfluxDB） | Ch02 存储基准 |
| rapids | RAPIDS cuML + LightGBM CUDA（本地构建） | 一个 Ch12 GPU 基准 |
常见安装踩坑排查
安装失败大多集中在平台与编译依赖，以下是高频问题与处理。
| 现象 | 原因 | 处理 |
|---|---|---|
| Windows PowerShell 直装失败 | scikit-learn 无 Windows wheel，源码编译失败 | 必须走 WSL2：wsl --install -d Ubuntu，再按 Linux 步骤 |
| uv sync 时 scikit-learn 编译报错 | 缺 C/C++ 编译器与 Python headers | Ubuntu/Debian/WSL2：sudo apt install build-essential python3-dev；macOS：xcode-select --install |
| Intel Mac uv 无法解析 PyTorch | PyTorch 不再发布 macOS x86_64 wheel | Intel Mac 只能用 Docker（Option A） |
| 数据下载耗时/空间不足 | firm-characteristics 面板约 4 GB | 加 --skip-firm-characteristics，约 75 MB 起步，需要时再下 |
| notebook 报数据集缺失 | Jupyter 把每章文件夹当 working directory | 用 ML4T_DATA_PATH 前缀给 loader 绝对路径 |
常见问题
Windows 能直接 pip 安装吗？
不能。官方明确说明 Windows 必须走 WSL2，PowerShell 直装不受支持；scikit-learn 在当前 Python 版本没有 Windows wheel，源码编译会失败。
安装要多少磁盘和多久？
本地 uv 路径约 16 GB（11 GB 环境 + 4 GB 免费数据 + 0.9 GB git），免费数据下载约 12 分钟；跳过 firm-characteristics 可约 75 MB 起步。
Docker 和 uv 怎么选？
多数人用 Docker（默认，环境自带）；Apple Silicon Mac 走本地 uv（发布前实测路径）；Intel Mac 只能 Docker（PyTorch 无 macOS x86_64 wheel）。
免费数据需要 API key 吗？
免费数据集（download_all.py --free-only）无需 key；另类数据、实盘接口等需要对应数据源或券商的 key/授权。
不想自己装环境怎么办？
如果只是想「一句话发起行情/选股/量化分析研究」而非系统学习，可看 EasyClaw 量化 Skill 免部署路线（见对比页）；不代表 ML4T 已集成 EasyClaw。