一、环境准备（核心避坑点）

1. Python 版本选择（重中之重）

   • ❌ 避免：Python 3.12+（包括你踩坑的 3.13），依赖库（如 faker、werkzeug 等）存在大量兼容性问题，会出现ImportError、AttributeError等奇葩报错。
   • ✅ 推荐：Python 3.11.8（稳定版，兼容所有 Label-Studio 依赖）。
   • 验证 Python 版本：

     python --version  # 输出需为Python 3.11.8
     

   • 若本地有多个 Python 版本，建议用py -3.11替代python命令（Windows），或用python3.11（Mac/Linux）。

2. 创建项目文件夹（规范命名）

   # 建议全英文、无空格，避免路径报错
   mkdir label-studio-project
   cd label-studio-project
   

   （Windows 也可手动新建文件夹，然后在文件夹内右键→“在终端中打开”，替代输入 cmd 的方式）

二、虚拟环境创建与激活（隔离依赖）

1. 创建虚拟环境

   # 指定Python3.11创建，避免系统默认版本干扰
   py -3.11 -m venv venv
   

   ✅ 验证：文件夹内出现venv目录，说明创建成功。

2. 激活虚拟环境

   • Windows（cmd）：

     venv\Scripts\activate
     

   • Windows（PowerShell）：

     .\venv\Scripts\Activate.ps1
     

     （若提示权限错误，先执行：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，按 Y 确认）
   • Mac/Linux：

     source venv/bin/activate
     

   ✅ 验证：命令行前缀出现(venv)，说明激活成功。

三、安装 Label-Studio（国内源加速）

# 使用清华源，避免官方源下载慢/失败
pip install label-studio -i https://pypi.tuna.tsinghua.edu.cn/simple

⚠️ 常见问题处理：

• 若报错error: Microsoft Visual C++ 14.0 or greater is required：下载安装Visual C++ 生成工具（勾选 “C++ 构建工具” 即可）。
• 若报错pip版本过低：先升级 pip：

  pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple
  

四、初始化与启动 Label-Studio

1. 初始化项目（全英文命名）

   # 替换为你的项目名，如label_demo，不要有中文/空格
   label-studio init label_demo
   

   • 首次执行会提示创建管理员账号：输入用户名（默认 admin）、密码（建议简单易记，如 123456）、邮箱（可填虚拟邮箱，如 admin@test.com）。

2. 启动 Label-Studio

   # 启动指定项目，自动占用可用端口（默认8080，被占用则自动递增）
   label-studio start label_demo
   

   ✅ 验证：

   • 命令行输出Running on http://localhost:8080（或 8081/8082 等）；
   • 自动打开浏览器，进入 Label-Studio 登录页面，用刚才设置的账号密码登录即可。

      

     

五、后续启动（简化步骤）

每次重启只需执行：

# 1. 进入项目文件夹
cd label-studio-project
# 2. 激活虚拟环境
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Mac/Linux
# 3. 启动项目
label-studio start label_demo

六、常见问题补充

1. 端口被占用：手动指定端口启动

   label-studio start label_demo --port 8088
   

2. 忘记管理员密码：重置密码

   label-studio reset-password
   

3. 退出虚拟环境：

   deactivate
   

总结

1. 核心避坑点：必须使用 Python 3.11.8 版本，高版本（3.12+）会因依赖不兼容导致部署失败；
2. 关键规范：项目文件夹 / 项目名需全英文、无空格，避免路径或命名引发的报错；
3. 高效技巧：使用国内镜像源安装依赖，激活虚拟环境后再操作，端口被占用时手动指定端口启动。