tensorchord/envd · 上手攻略

仓库：tensorchord/envd
链接：https://github.com/tensorchord/envd
分类：engineering / llm-infra（AI/ML 可复现开发环境）
作者：spark
更新：2026-07-26

一、是什么

envd（ɪnˈvdɪ，读作 "in-video"）是 TensorChord 开源的一个面向 AI/ML 的容器化开发环境构建工具。它用一个声明式的 build.envd 文件描述你的训练/推理环境，然后用一个 envd up 命令把它打包成 OCI 兼容的镜像，并在本地（或远端 K8s 集群）跑起来。

它不是 Dockerfile 的替代品那种简单封装——它瞄准的是"今天 Python + CUDA + Conda + 自定义 BASH + 一堆破包"的混乱现实，把"声明环境 + 复现 + 上 K8s + 缓存加速"做成一条龙。底层用 buildkit 做镜像构建，但前面盖了一层类似 Nix/函数式的小 DSL，让 ML 工程师不用写 Dockerfile 也能拿到可复现环境。

主语言 Go，二进制发布 + PyPI 包装，Apache-2.0。Stars ~2.2k，最近仍在提交（2026-07-25）。当前主线版本号：v0.4.3（README 示例里用的就是这个），并已发布 v1.0 语法（默认 builder 切换为 moby-worker）。下面命令示例以 v0.x 主流语法为准。

二、解决什么问题

AI/ML 项目里，环境总是最痛的一环：

"在我机器上能跑"——同事复现不了；
Dockerfile 又长又脆，PyPI / APT 没缓存每次重下；
本地写，集群跑，环境两边对不齐；
CUDA 版本、驱动、cuDNN 对不上；
团队里每个人都要重复一遍 Docker 入门教育。

envd 对位：

声明式环境：build.envd 用 Python-like 函数描述依赖，谁看了都懂；
可复现：OCI 镜像可推到 Harbor / Docker Hub；
PyPI / APT 缓存：buildkit 配合 python-cache/apt-cache，第二次构建省时；
本地↔集群同源：envd context use local / envd context use cluster 切换，命令不变；
团队复用：include("https://github.com/x/y") 直接拉远端 envdlib，复用别人写好的"装 TensorBoard / 启 Jupyter / 配 CUDA"函数；
支持 GPU/CUDA、多语言（Python / R / Julia）；
vscode / jupyter 集成：开箱即用 SSH 接入容器、内置 Jupyter。

三、快速安装

前置：Docker ≥ 20.10.0。

3.1 pip 装（最常见）

pip install --upgrade envd
envd bootstrap

bootstrap 会准备默认 builder 镜像（带 buildkit）。国内网络可配 Docker Hub 镜像加速：

envd bootstrap --dockerhub-mirror https://docker.mirrors.sjtug.sjtu.edu.cn
# 或清华 TUNA / 中科大等

3.2 直接下二进制

到 GitHub Releases 页面下载对应平台（envd 静态二进制），放到 PATH，然后同样跑 envd bootstrap。

3.3 验证

envd version
docker images | grep envd   # 应该能看到 base 镜像被拉下来

四、核心用法

4.1 最小例子（Python + NumPy + fish shell）

克隆示例：

git clone https://github.com/tensorchord/envd-quick-start.git
cd envd-quick-start

build.envd 内容（关键片段）：

def build():
    base(dev=True)
    install.conda()
    install.python()
    # 配 pip 镜像（国内场景）
    # config.pip_index(url = "https://pypi.tuna.tsinghua.edu.cn/simple")
    install.python_packages(name = [
        "numpy",
    ])
    shell("fish")

构建并启动：

envd up

第一次会下载 base 镜像、装包、起容器，最后进 fish shell。提示 Welcome to fish... 时就进了"容器版开发环境"。

后台跑 + 拿 Jupyter：

envd up --detach
envd envs ls
# NAME                JUPYTER                 ...
# envd-quick-start    http://localhost:42779  ...

把 Jupyter 端口打开：去掉 build.envd 里 config.jupyter() 的注释再 envd up 一次。

4.2 用 envdlib 复用别人写好的"函数"

官方维护了一个 envdlib：https://github.com/tensorchord/envdlib，里面有 tensorboard()、jupyter()、pytorch()、cuda() 之类封装好的片段。

envdlib = include("https://github.com/tensorchord/envdlib")

def build():
    base(dev=True)
    install.conda()
    install.python()
    envdlib.tensorboard(host_port=8888)
    envdlib.cuda(version="11.8.0")

团队内部可以维护自己的私有 envdlib 仓库，把"装什么包、起什么 daemon、暴露什么端口"标准化。

4.3 本地↔集群切换

envd context use local      # 本地 Docker
envd up

envd context use cluster    # 远端 K8s（要先做集群配置）
envd up

集群端会推镜像到仓库（你配置的 registry）并在 K8s 里起 Pod，本地交互体验不变。详见官方 K8s 文档。

4.4 v0 vs v1 语法

README 末尾给了一张对照表：

特性	v0	v1
dev 支持	✅	✅
CUDA 支持	✅	✅
serving（推理部署）	⚠️	✅
自定义 base image	⚠️	✅
多语言	⚠️	✅
moby builder	❌	✅

⚠️ v1.0 起 v1 语法默认开，且 builder 默认是 moby-worker。新项目建议直接看 v1 文档；老项目继续用 v0 语法仍兼容。

4.5 常用命令速查

envd up                   # 构建 + 起容器 + 进入
envd up --detach          # 后台起
envd up --rebuild         # 强制重新构建
envd envs ls              # 看当前所有环境（包含 jupyter 端口）
envd context ls           # 看 context
envd context use <name>   # 切换 local / cluster
envd destroy              # 销毁环境

五、典型适用场景

ML 团队的标准化环境：把"装 CUDA + 装 Python + 装 PyTorch + 启 TensorBoard"做成 envdlib，新人一行 envd up 就齐活。
可复现的科研 / 论文代码：build.envd 进 repo，审稿人/合作者一键复现。
本地写、集群训：local↔cluster 一键切换，本地用 GPU 工作站，CI 或大训练上 K8s。
Agent / 内部工具的运行时：Agent 框架需要"统一可复现的 Python 环境 + GPU"，envd 是顺手的选择。
替代 Dockerfile 入门教学：让算法同学不用碰 Docker 也能产出可复现环境。

六、坑与注意

生态比 Nix/Dockerfile 小：很多人不熟 build.envd 语法，跨团队推广要带培训成本；遇到小众 CUDA / 驱动组合可能要去翻 issue。
Windows / macOS Apple Silicon 体验有差：底层依赖 Docker Desktop，GPU 透传在 macOS 上基本只能跑 CPU，Linux + 真 NVIDIA GPU 才是"完整 envd"主场。
缓存默认从 docker.io 拉：国内经常被卡；务必 bootstrap --dockerhub-mirror，或自己配私有 registry + envdlib。
v0 → v1 是分水岭：v1 引入 moby builder、serving、多语言、自定义 base，部分老 build.envd 迁移要做小改写，按官方迁移指南走。
没有锁定 base 镜像版本时，依赖会随时间漂移：要可复现就别忘了 base(image="...", dev=True) 之类的版本固定写法（v1 强项）。
不是替代 docker compose：envd 偏"环境 + 训练/交互"，多服务编排（web + db + cache）仍应交给 compose 或 K8s。
构建日志噪声不小：首次 envd up 看着像在刷 docker build，要耐心；第二次以后增量构建很快。

七、与同类对比

方案	形态	关键差异
envd	声明式 + CLI，构建 OCI 镜像	面向 ML，buildkit 加速缓存，local↔cluster 同源
Dockerfile + Docker Compose	通用	灵活但要手写缓存、CUDA 那些坑；团队复用靠复制粘贴
Nix / NixOS	函数式系统级	极强可复现但学习曲线陡、跨平台不如 envd 顺
Conda env + pip	纯 Python	上手最易，但跨语言 / GPU / 部署到 K8s 全要自己拼
Devcontainer (VS Code)	JSON 配置 + Docker	跟 IDE 深度绑定，但多语言/集群侧偏弱
Repo2Docker / JupyterHub	镜像构建	偏 Jupyter 生态；envd 更通用也支持 K8s
Singularity / Apptainer	HPC 场景	适合 HPC 集群单文件交付，envd 偏开发-部署一体

八、一句话推荐

envd 是 AI/ML 团队做"声明式 + 可复现 + 本地↔集群同源"的开发环境利器，比 Dockerfile 友好、比 Nix 易学，比 Conda 强在 GPU 和 K8s 一条龙——尤其适合要把新人 onboarding 时间从一天压缩到一杯咖啡的算法平台团队。 Windows / macOS / 强 Windows 场景请谨慎评估，主要价值在 Linux + NVIDIA。