Label Studio 安装与升级完全指南pip、Homebrew、Docker、源码编译与离线部署【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioLabel Studio 是一款支持图像、文本、音频、视频等多类型数据标注的开源工具其服务端基于 Python/Django 构建。本文以官方安装文档为核心系统梳理从环境准备、pip/Homebrew/Docker/源码/Anaconda 等多种安装方式到数据库选型、升级迁移与常见启动参数的完整链路读者可按自身操作系统与网络环境选择最合适的方案并在安装后快速完成服务启动、端口调整与数据持久化配置。文中所有命令与配置均可直接复制使用并附上当前开源仓库中的实现细节作为佐证。安装前的系统与环境要求在开始安装之前先确认你的环境满足 Label Studio 的基础要求。综合 安装文档 与其引用的系统要求说明见 docs/source/includes/deploy.md需要关注以下几点操作系统支持 Linux、Windows、macOS文档同时提到可使用 Ubuntu、Anaconda 等场景。Python 版本安装文档要求 Python 3.8 或更高版本系统要求部分注明 Python 3.6 以上即可运行以 pip 安装方式为准建议使用较新的稳定版本。仓库 Dockerfile 中镜像构建使用 Python 3.13。端口要求默认监听8080端口需保证该端口未被占用如需更换端口可在启动时指定见下文安装后的启动与常用参数。软件要求PostgreSQL 14 或更高版本或 SQLite 3.35 或更高版本SQLite 为默认数据库无需额外配置。硬件建议磁盘空间按标注数据量规划——以 SQLite 为后端时约 100 万条标注任务占用约 2.3GB 磁盘生产环境建议预留 50GB。内存建议最低 8GB推荐 16GB如 AWS t3.large 或 t3.xlarge 规格。浏览器支持官方在最新版 Google Chrome 上完成测试使用其他浏览器或旧版本浏览器可能出现非预期行为。此外官方强烈建议在干净的 Python 虚拟环境venv 或 conda中安装以降低包冲突或依赖缺失的风险。使用 pip 安装pip 是最轻量、最通用的安装方式适用于 Python 环境就绪的 Linux / macOS / Windows 机器。方式一虚拟环境 pip推荐python3 -m venv env source env/bin/activate python -m pip install label-studio方式二直接安装pip install label-studio安装完成后执行以下命令启动服务label-studio默认浏览器会自动打开 http://localhost:8080 进入 Label Studio 界面。label-studio命令在仓库中的实际入口定义于 pyproject.toml 的[project.scripts]段label-studio label_studio.server:main也就是说label-studio最终调用的是 label_studio/server.py 中的main函数。从源码可以看到启动流程中的几个关键环节_setup_env()会注入项目路径并设置DJANGO_SETTINGS_MODULElabel_studio.core.settings.label_studio见 server.py_apply_database_migrations()会在首次启动时自动检测数据库是否同步并自动执行migrate初始化见 server.py这也是为什么安装后直接label-studio即可运行、无需手动建库默认用户名为default_userlocalhost见 server.py。关于启动时的更多选项端口、宿主、数据库路径等见下文安装后的启动与常用参数小节。使用 Homebrew 安装macOSmacOS 用户可通过 Homebrew 包管理器安装前提是本机已安装 brew 包管理器。先添加官方 tap 源再安装brew tap humansignal/tap brew install humansignal/tap/label-studio安装完成后同样执行label-studio启动浏览器自动打开 http://localhost:8080。注意如果你此前使用的是旧组织名heartexlabs/tap的 brew tap无需立即迁移——旧 tap 已配置为humansignal/tap的镜像现有用户可平滑过渡不受影响。使用 Docker 安装Docker 方式免去了本地 Python 环境的搭建适合快速试用、生产部署与团队分发前提是本机已安装 Docker。在 *nix 系统上安装以下命令启动容器并映射到本机8080端口同时将标注数据持久化到当前目录的./mydata文件夹docker run -it -p 8080:8080 -v $(pwd)/mydata:/label-studio/data heartexlabs/label-studio:latest重要提示官方镜像以**非 root 用户UID 1001**运行容器。因此通过-v挂载的目录和文件必须授予 UID 1001 适当的读写权限否则容器内应用将无法写入数据。这一点在 DockerfileUSER 1001与start.md文档中均被反复强调。在 Windows 上安装Windows 下需要调整-v卷路径的写法。Command Linecmddocker run -it -p 8080:8080 -v %cd%/mydata:/label-studio/data heartexlabs/label-studio:latest label-studio --log-level DEBUGPowerShelldocker run -it -p 8080:8080 -v ${PWD}/mydata:/label-studio/data heartexlabs/label-studio:latest label-studio --log-level DEBUG覆盖默认启动命令Docker 启动后默认执行label-studio你可以在镜像名之后追加新的参数来覆盖默认行为。上例中追加的label-studio --log-level DEBUG即表示以 DEBUG 日志级别启动服务。从源码构建本地镜像docker build -t heartexlabs/label-studio:latest .仓库根目录的 Dockerfile 展示了完整的多阶段构建流程frontend-builder阶段用 Bun 编译前端资源venv-builder阶段用 uv 依据pyproject.toml/uv.lock安装 Python 依赖最终production阶段合成包含 Label Studio、Nginx 和 uwsgi 的运行镜像并设置EXPOSE 8080、以./deploy/docker-entrypoint.sh作为入口。使用 Docker Compose 启动仓库根目录提供了开箱即用的 docker-compose.yml启动命令如下要求 Docker Compose 1.25.0 或更高版本docker-compose up -d与单容器方式不同该 Compose 编排包含三个服务nginx对外暴露8080:8085与8081:8086端口代理前端请求并支持通过deploy/nginx/certs目录挂载 SSL 证书实现 HTTPS 终结appLabel Studio 应用本体通过label-studio-uwsgi命令以 uWSGI 运行监听容器内8000端口其进程模型配置见 deploy/uwsgi.ini默认 4 个进程支持按内存/时长自动回收 workerdbPostgreSQL 17 数据库pgautoupgrade/pgautoupgrade:17-alpine数据卷持久化到./postgres-data并预留了deploy/pgsql/certs的 TLS 配置入口。Compose 中已经为 app 服务写好了 PostgreSQL 连接环境变量POSTGRE_NAME、POSTGRE_USER、POSTGRE_HOSTdb等因此docker-compose up -d即可获得应用 Nginx PostgreSQL的完整后端。如果你希望脱离 Compose 单独使用 PostgreSQL请参考 数据库存储配置。内网 / 无互联网环境安装如果目标服务器无法访问外网可以在有网络的机器上完成镜像导出与导入# 在有网络的机器上下载镜像 docker pull heartexlabs/label-studio:latest # 导出为 tar 归档可压缩 docker save heartexlabs/label-studio:latest | gzip label_studio_latest.tar.gz # 传输到目标机器 scp label_studio_latest.tar.gz ANOTHER_HOST:/tmp # 在目标机器上导入镜像 docker image import /tmp/label_studio_latest.tar.gz导入完成后按上文使用 Docker 安装的步骤启动即可。在 Ubuntu 上安装Ubuntu 用户同样推荐虚拟环境方案并额外安装 Python 3.9 开发包以满足编译依赖python3 -m venv env source env/bin/activate sudo apt install python3.9-dev python -m pip install label-studio从源码安装如果你需要使用夜间构建版本、二次开发或深度定制功能可以从源码构建。通过 Git 克隆仓库也可以直接使用本仓库作为源码根目录然后使用 Poetry 管理依赖git clone https://gitcode.com/GitHub_Trending/la/label-studio.git # 进入项目目录并安装依赖 cd label-studio pip install poetry poetry install # 执行数据库迁移 poetry run python label_studio/manage.py migrate # 收集静态文件 poetry run python label_studio/manage.py collectstatic # 以开发模式启动服务访问 http://localhost:8080 poetry run python label_studio/manage.py runserver源码安装的入口与 pip 安装一致——manage.py最终同样经由 Django 的runserver命令启动对应 server.py 中_app_run的call_command(runserver, --noreload, ...)。如果不想使用 Poetry也可以参考 安装要求文档 中的pip install -e .方式。使用 Anaconda 安装通过 conda 创建独立环境注意安装文档提示psycopg2仅在 Label Studio 1.7.2 版本需要手动安装conda create --name label-studio conda activate label-studio conda install psycopg2 # 仅 LS 1.7.2 需要 pip install label-studio安装后的启动与常用参数安装完成后可通过label-studio start显式启动服务默认使用 SQLite 数据库存储标注任务与标注结果。常用命令与参数如下详见 启动文档命令说明label-studio启动 Label Studio 服务器label-studio -h/label-studio --help显示全部命令行参数label-studio init project_name [参数]初始化指定项目label-studio start project_name --init [参数]启动服务器并初始化项目label-studio reset_password重置指定用户的密码label-studio shell进入 Django shell直接操作数据label-studio version显示版本号并退出label-studio user --username email显示用户信息与 API token部分常用启动参数均可通过命令行或环境变量指定命令行参数环境变量默认值说明-b/--no-browser无False启动时不自动打开浏览器-db/--databaseLABEL_STUDIO_DATABASElabel_studio.sqlite3指定数据库文件路径--data-dirLABEL_STUDIO_BASE_DATA_DIR随系统而定应用数据存放目录-d/--debug无False开启调试模式-p/--portLABEL_STUDIO_PORT8080Web 服务端口--hostLABEL_STUDIO_HOST外部访问域名/子路径用于生成资源链接--log-level无ERROR日志级别DEBUG / INFO / WARNING / ERROR--usernameLABEL_STUDIO_USERNAMEdefault_userlocalhost默认用户用户名--passwordLABEL_STUDIO_PASSWORD无默认用户密码--user-tokenLABEL_STUDIO_USER_TOKEN自动生成用户 API 认证 token--sampling无sequential任务采样顺序sequential / uniform无LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLEDFalse允许访问本地文件目录Docker 场景无LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT/本地文件访问根目录更换端口示例label-studio start --port 9001或设置环境变量LABEL_STUDIO_PORT9001。Docker 场景下则通过端口映射实现例如将容器 8080 映射到宿主机 9001docker run -it -p 9001:8080 -v $(pwd)/mydata:/label-studio/data heartexlabs/label-studio:latest label-studio使用外部域名/子路径多人协作或需要固定资源地址时可通过--host或LABEL_STUDIO_HOST指定完整协议与域名例如https://subdomain.example.com:7777注意必须携带http://或https://前缀。数据库后端选择默认 SQLite 适合数万级任务的小规模项目若计划标注百万级任务、存在大量并发用户或使用复杂筛选官方建议改用 PostgreSQL连接参数POSTGRE_NAME、POSTGRE_USER、POSTGRE_PASSWORD、POSTGRE_PORT、POSTGRE_HOST等详见 数据库存储配置。此外docker-compose.minio.yml 提供了与 S3 兼容的 MinIO 对象存储示例可用于生产级数据存储方案。升级 Label Studio使用 pip 直接升级到最新版本pip install --upgrade label-studio版本迁移提示当从 0.9.1 或更早版本升级到 1.0.0 时会自动运行迁移脚本。为确保已有项目完成迁移请在启动时显式指定旧项目路径label-studio start path/to/old/project1.0.0 版本最需要关注的变化是旧的completions 字段已重命名为 annotations已完成任务的 JSON 导出格式相应改变详见 数据导出文档。若你曾定制过 Label Studio 前端请参考 前端参考指南 中的更新说明以保持与 1.0.0 的兼容性。更多资源与故障排查安装/升级的完整前提条件清单见 安装要求文档启动参数、环境变量设置与任务采样方式见 启动文档数据库与对象存储PostgreSQL、SQLite、MinIO配置见 数据库存储配置常见安装问题与解决办法见 安装故障排查文档Kubernetes 环境部署见 Kubernetes 安装文档。选择与你的操作系统、网络环境和数据规模匹配的安装方式即可快速启动一套可用于图像、文本、音频、视频等多类型任务的标注平台。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考