Label Studio 安装与环境要求完全指南系统需求、pip/Docker/源码部署与升级路径【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio本指南以 Label Studio 官方安装要求文档docs/source/guide/install_requirements.md为主体系统梳理从环境检查、系统软硬件要求到 pip、Docker、Docker Compose、Ubuntu、Anaconda、源码编译等多种安装路径以及从旧版本升级的关键注意事项。读完本文你将掌握 Label Studio 在不同操作系统与部署形态下的完整安装流程、端口与存储规划、数据库选择原则以及升级到 1.0.0 版本时的迁移要点。安装前的系统要求在动手安装之前先对照以下硬件、端口与软件要求评估你的运行环境。操作系统与 Python 版本Label Studio 可在 Linux、Windows 或 macOS 上运行。官方推荐在干净的 Python 环境中安装尤其建议使用虚拟环境venv 或 conda以最大程度降低包冲突或依赖缺失的风险见 docs/source/guide/install_requirements.md。关于 Python 版本不同安装方式的官方表述有所差异需要注意区分pip 安装方式要求Python 3.8 或更高版本从当前仓库的 pyproject.toml 可以看到现代版本1.x实际声明requires-python 3.10,4即Python 3.10 及以上构建工具链ruff的目标版本也锁定为py310。也就是说如果你安装的是最新版 Label Studio建议直接使用 Python 3.10 的环境避免因解释器版本过低导致依赖解析失败。源码中的label-studio命令行入口定义在 pyproject.tomllabel-studio label_studio.server:main即label-studio命令实际对应 label_studio/server.py 中的main()函数。端口要求Label Studio 默认监听8080 端口。如需使用其他端口可在启动时通过--port参数指定例如label-studio start --port 9001也可以设置环境变量LABEL_STUDIO_PORT9001。关于启动参数与环境变量的完整对应关系参见 docs/source/guide/start.md。从源码看端口解析逻辑位于 label_studio/server.py内部端口依次从命令行--port、环境变量PORT、配置项port默认 8080取值且若端口被占用会自动向上尝试最多 1000 个新端口非 debug 模式见 label_studio/server.py并将最终端口写入settings.INTERNAL_PORT。服务器资源要求磁盘与内存官方给出的基准建议来自 docs/source/includes/deploy.md磁盘磁盘空间按计划标注的数据量分配。以 SQLite 数据库为例100 万条标注任务约占 2.3GB 磁盘空间生产环境建议预留50GB 磁盘空间内存最低8GB RAM推荐16GB RAM例如 AWS 的 t3.large 或 t3.xlarge 实例数据库软件PostgreSQL 14 或更高版本或 SQLite 3.35 或更高版本。关于数据库选型的进一步说明SQLite 适合数万条任务规模的项目如果需要标注百万级任务、大量并发用户或复杂的数据管理过滤器建议使用 PostgreSQL详见 docs/source/guide/storedata.md。使用 pip 安装Python 虚拟环境这是最常用的开发安装方式。以下命令依次创建并激活虚拟环境、安装 Label Studiopython3 -m venv env source env/bin/activate python -m pip install label-studio如果不想使用虚拟环境也可以直接安装仍要求 Python 3.8pip install label-studio安装完成后直接启动服务label-studio默认浏览器会自动打开 http://localhost:8080 并进入 Label Studio 界面。启动时的更多选项如指定端口、host、采样策略等参见 docs/source/guide/start.md。补充说明安装完成后label-studio可执行命令即由包管理器注册入口见 pyproject.toml。服务启动时 label_studio/server.py 会自动检查数据库迁移状态并执行migrate因此首次启动无需手动迁移数据库。使用 Docker 安装Label Studio 也提供了官方 Docker 镜像前提是本机已安装 Docker。在 *nix 系统上用 Docker 安装以下命令会启动 Label Studio 并监听 8080 端口同时把标注数据持久化到宿主机当前目录下的mydata文件夹挂载到容器内的/label-studio/datadocker run -it -p 8080:8080 -v $(pwd)/mydata:/label-studio/data heartexlabs/label-studio:latest重要提示由于镜像以**非 root 用户UID 1001**运行挂载的文件和目录必须具有 UID 1001 可读写的正确权限。该约束在 Dockerfile 中以chown -R 1001:0固化并在 Dockerfile 通过USER 1001切换用户。在 Windows 上用 Docker 安装Windows 上需要修改-v卷路径的写法。Windows 命令行cmddocker 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注意这两个示例在镜像命令尾部追加了label-studio --log-level DEBUG这是覆盖默认 Docker 启动参数的典型用法——docker run中镜像名之后的参数会替换镜像默认的 CMD。默认 CMD 定义在 DockerfileENTRYPOINT [./deploy/docker-entrypoint.sh]、CMD [label-studio]入口脚本 deploy/docker-entrypoint.sh 会先执行docker-entrypoint.d下的初始化脚本数据库等待、迁移等再以exec方式启动传入的命令。本地构建 Docker 镜像如果想基于当前源码构建本地镜像在仓库根目录执行docker build -t heartexlabs/label-studio:latest .从 Dockerfile 可以看到构建流程分为多个阶段uv固定 uv 二进制、frontend-builder用 Bun 编译前端资源、venv-builder准备 Python 虚拟环境并执行collectstatic、production最终镜像内含 Nginx。构建时默认使用 Python 3.13 与 Node 22见 Dockerfile。生产镜像通过 deploy/default.conf 提供 Nginx 配置并暴露 8080 端口Dockerfile。使用 Docker Compose 运行仓库根目录提供了 docker-compose.yml用于一键启动包含 Nginx、应用与 PostgreSQL 的完整栈服务地址为http://localhost:8080。使用前提是Docker Compose 1.25.0 或更高版本。docker-compose up -d该命令会以 PostgreSQL 作为数据库后端启动 Label Studio。从 docker-compose.yml 可以看到三个服务nginx对外暴露 8080/8081 端口代理到 appapp运行label-studio-uwsgi对应 deploy/uwsgi.ini通过POSTGRE_*环境变量连接数据库db使用pgautoupgrade/pgautoupgrade:17-alpine镜像的 PostgreSQL 17。不借助 Docker Compose 也可以单独配置 PostgreSQL 数据库连接具体参见 docs/source/guide/storedata.md。离线安装无互联网环境如果目标机器无法访问互联网可以在一台有网络且有 Docker 的机器上完成以下步骤拉取镜像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:/tmpSSH 登录目标机器并导入镜像docker image import /tmp/label_studio_latest.tar.gz随后按照 Docker 安装步骤启动即可参考 docs/source/guide/install.md 中的 Install with Docker 一节。在 Ubuntu 上安装Ubuntu 用户可以在虚拟环境中执行以下命令完成安装。其中sudo apt install python3.9-dev用于安装 Python 开发头文件编译部分依赖时需要python3 -m venv env source env/bin/activate sudo apt install python3.9-dev python -m pip install label-studio提示如使用更新的 Ubuntu 发行版可将python3.9-dev替换为对应版本如python3.11-dev以便与系统默认 Python 版本匹配。若在纯净 venv 下安装最新版 Label Studio建议确保 Python 不低于 3.10见前文 pyproject.toml 的版本约束。从源码安装开发模式如果你需要使用 nightly 构建或扩展 Label Studio 功能可以克隆源码并本地运行git clone https://github.com/HumanSignal/label-studio.git cd label-studio # 安装所有包依赖 pip install -e . # 运行数据库迁移 python label_studio/manage.py migrate # 以开发模式启动服务器地址为 http://localhost:8080 python label_studio/manage.py runserver上述命令中的python label_studio/manage.py migrate直接调用 label_studio/manage.py 的 Django 管理命令而runserver对应 Django 内置开发服务器。生产形态下Docker 镜像则通过 uWSGIdeploy/uwsgi.ini承载 WSGI 应用入口为 label_studio/core/wsgi.py。使用 Anaconda 安装如果你使用 conda 管理 Python 环境可以这样安装conda create --name label-studio conda activate label-studio pip install label-studio即在新建的 conda 环境中仍然通过 pip 安装 Label Studio 包这样既能隔离环境又能获得 PyPI 上的最新发布版本。升级 Label Studio使用 pip 升级到最新版pip install --upgrade label-studio升级后重启服务即可。服务启动时会自动检查并执行数据库迁移label_studio/server.py因此无需手工处理增量迁移。从 0.9.1 及更早版本升级到 1.0.0当从0.9.1 或更早版本升级到1.0.0时会触发迁移脚本用于把旧版项目数据迁移到新数据库。为确保已有项目被正确迁移启动时应显式指定旧项目路径label-studio start path/to/old/project从源码可以印证这条迁移链路label_studio/server.py 中start命令会检测指定路径下是否存在旧版config.json与config.xml若存在则调用 label_studio/core/old_ls_migration.py 中的migrate_existing_project完成项目迁移迁移完成后旧项目文件夹即可废弃。升级时的两个关键变化升级到 1.0.0 后需要重点关注以下两点字段重命名completions 被重命名为 annotations已完成任务的 JSON 导出格式随之变化详见 docs/source/guide/export.md 中的原始 JSON 格式说明前端定制兼容性如果你自定义过 Label Studio 前端需要参考 docs/source/guide/frontend_reference.md 进行必要的更新以保持与 1.0.0 的兼容。常见问题速查问题解决方案默认端口 8080 被占用使用label-studio start --port 新端口或设置LABEL_STUDIO_PORT环境变量源码层面还会自动探测空闲端口Docker 挂载目录无权限确保宿主机目录对容器内 UID 1001 可读写生产环境标注量很大从 SQLite 切换到 PostgreSQL见 docs/source/guide/storedata.md并保证内存 ≥ 16GB升级后旧项目数据消失用label-studio start path/to/old/project显式触发旧项目迁移离线服务器安装使用docker pulldocker savescpdocker image import离线搬运镜像小结Label Studio 提供了从个人开发到生产部署的完整安装矩阵本地快速上手推荐 pip 虚拟环境团队协作与生产环境推荐 Docker Compose PostgreSQL定制开发推荐源码安装。安装前重点核对 Python 版本3.10、8080 端口可用性、磁盘与内存预算以及挂载卷的 UID 1001 权限升级时则要留意 1.0.0 的 completions→annotations 重命名与前端兼容性要求。结合本文引用的 pyproject.toml、Dockerfile、docker-compose.yml 与 label_studio/server.py 源码你可以进一步深入理解每条安装路径背后的实现细节。【免费下载链接】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），仅供参考 
长河君 · 2026/9/11 13:19:30 · 阅读 1.2k Label Studio 安装与环境要求完全指南：系统需求、pip/Docker/源码部署与升级路径
Label Studio 安装与环境要求完全指南系统需求、pip/Docker/源码部署与升级路径【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio本指南以 Label Studio 官方安装要求文档docs/source/guide/install_requirements.md为主体系统梳理从环境检查、系统软硬件要求到 pip、Docker、Docker Compose、Ubuntu、Anaconda、源码编译等多种安装路径以及从旧版本升级的关键注意事项。读完本文你将掌握 Label Studio 在不同操作系统与部署形态下的完整安装流程、端口与存储规划、数据库选择原则以及升级到 1.0.0 版本时的迁移要点。安装前的系统要求在动手安装之前先对照以下硬件、端口与软件要求评估你的运行环境。操作系统与 Python 版本Label Studio 可在 Linux、Windows 或 macOS 上运行。官方推荐在干净的 Python 环境中安装尤其建议使用虚拟环境venv 或 conda以最大程度降低包冲突或依赖缺失的风险见 docs/source/guide/install_requirements.md。关于 Python 版本不同安装方式的官方表述有所差异需要注意区分pip 安装方式要求Python 3.8 或更高版本从当前仓库的 pyproject.toml 可以看到现代版本1.x实际声明requires-python 3.10,4即Python 3.10 及以上构建工具链ruff的目标版本也锁定为py310。也就是说如果你安装的是最新版 Label Studio建议直接使用 Python 3.10 的环境避免因解释器版本过低导致依赖解析失败。源码中的label-studio命令行入口定义在 pyproject.tomllabel-studio label_studio.server:main即label-studio命令实际对应 label_studio/server.py 中的main()函数。端口要求Label Studio 默认监听8080 端口。如需使用其他端口可在启动时通过--port参数指定例如label-studio start --port 9001也可以设置环境变量LABEL_STUDIO_PORT9001。关于启动参数与环境变量的完整对应关系参见 docs/source/guide/start.md。从源码看端口解析逻辑位于 label_studio/server.py内部端口依次从命令行--port、环境变量PORT、配置项port默认 8080取值且若端口被占用会自动向上尝试最多 1000 个新端口非 debug 模式见 label_studio/server.py并将最终端口写入settings.INTERNAL_PORT。服务器资源要求磁盘与内存官方给出的基准建议来自 docs/source/includes/deploy.md磁盘磁盘空间按计划标注的数据量分配。以 SQLite 数据库为例100 万条标注任务约占 2.3GB 磁盘空间生产环境建议预留50GB 磁盘空间内存最低8GB RAM推荐16GB RAM例如 AWS 的 t3.large 或 t3.xlarge 实例数据库软件PostgreSQL 14 或更高版本或 SQLite 3.35 或更高版本。关于数据库选型的进一步说明SQLite 适合数万条任务规模的项目如果需要标注百万级任务、大量并发用户或复杂的数据管理过滤器建议使用 PostgreSQL详见 docs/source/guide/storedata.md。使用 pip 安装Python 虚拟环境这是最常用的开发安装方式。以下命令依次创建并激活虚拟环境、安装 Label Studiopython3 -m venv env source env/bin/activate python -m pip install label-studio如果不想使用虚拟环境也可以直接安装仍要求 Python 3.8pip install label-studio安装完成后直接启动服务label-studio默认浏览器会自动打开 http://localhost:8080 并进入 Label Studio 界面。启动时的更多选项如指定端口、host、采样策略等参见 docs/source/guide/start.md。补充说明安装完成后label-studio可执行命令即由包管理器注册入口见 pyproject.toml。服务启动时 label_studio/server.py 会自动检查数据库迁移状态并执行migrate因此首次启动无需手动迁移数据库。使用 Docker 安装Label Studio 也提供了官方 Docker 镜像前提是本机已安装 Docker。在 *nix 系统上用 Docker 安装以下命令会启动 Label Studio 并监听 8080 端口同时把标注数据持久化到宿主机当前目录下的mydata文件夹挂载到容器内的/label-studio/datadocker run -it -p 8080:8080 -v $(pwd)/mydata:/label-studio/data heartexlabs/label-studio:latest重要提示由于镜像以**非 root 用户UID 1001**运行挂载的文件和目录必须具有 UID 1001 可读写的正确权限。该约束在 Dockerfile 中以chown -R 1001:0固化并在 Dockerfile 通过USER 1001切换用户。在 Windows 上用 Docker 安装Windows 上需要修改-v卷路径的写法。Windows 命令行cmddocker 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注意这两个示例在镜像命令尾部追加了label-studio --log-level DEBUG这是覆盖默认 Docker 启动参数的典型用法——docker run中镜像名之后的参数会替换镜像默认的 CMD。默认 CMD 定义在 DockerfileENTRYPOINT [./deploy/docker-entrypoint.sh]、CMD [label-studio]入口脚本 deploy/docker-entrypoint.sh 会先执行docker-entrypoint.d下的初始化脚本数据库等待、迁移等再以exec方式启动传入的命令。本地构建 Docker 镜像如果想基于当前源码构建本地镜像在仓库根目录执行docker build -t heartexlabs/label-studio:latest .从 Dockerfile 可以看到构建流程分为多个阶段uv固定 uv 二进制、frontend-builder用 Bun 编译前端资源、venv-builder准备 Python 虚拟环境并执行collectstatic、production最终镜像内含 Nginx。构建时默认使用 Python 3.13 与 Node 22见 Dockerfile。生产镜像通过 deploy/default.conf 提供 Nginx 配置并暴露 8080 端口Dockerfile。使用 Docker Compose 运行仓库根目录提供了 docker-compose.yml用于一键启动包含 Nginx、应用与 PostgreSQL 的完整栈服务地址为http://localhost:8080。使用前提是Docker Compose 1.25.0 或更高版本。docker-compose up -d该命令会以 PostgreSQL 作为数据库后端启动 Label Studio。从 docker-compose.yml 可以看到三个服务nginx对外暴露 8080/8081 端口代理到 appapp运行label-studio-uwsgi对应 deploy/uwsgi.ini通过POSTGRE_*环境变量连接数据库db使用pgautoupgrade/pgautoupgrade:17-alpine镜像的 PostgreSQL 17。不借助 Docker Compose 也可以单独配置 PostgreSQL 数据库连接具体参见 docs/source/guide/storedata.md。离线安装无互联网环境如果目标机器无法访问互联网可以在一台有网络且有 Docker 的机器上完成以下步骤拉取镜像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:/tmpSSH 登录目标机器并导入镜像docker image import /tmp/label_studio_latest.tar.gz随后按照 Docker 安装步骤启动即可参考 docs/source/guide/install.md 中的 Install with Docker 一节。在 Ubuntu 上安装Ubuntu 用户可以在虚拟环境中执行以下命令完成安装。其中sudo apt install python3.9-dev用于安装 Python 开发头文件编译部分依赖时需要python3 -m venv env source env/bin/activate sudo apt install python3.9-dev python -m pip install label-studio提示如使用更新的 Ubuntu 发行版可将python3.9-dev替换为对应版本如python3.11-dev以便与系统默认 Python 版本匹配。若在纯净 venv 下安装最新版 Label Studio建议确保 Python 不低于 3.10见前文 pyproject.toml 的版本约束。从源码安装开发模式如果你需要使用 nightly 构建或扩展 Label Studio 功能可以克隆源码并本地运行git clone https://github.com/HumanSignal/label-studio.git cd label-studio # 安装所有包依赖 pip install -e . # 运行数据库迁移 python label_studio/manage.py migrate # 以开发模式启动服务器地址为 http://localhost:8080 python label_studio/manage.py runserver上述命令中的python label_studio/manage.py migrate直接调用 label_studio/manage.py 的 Django 管理命令而runserver对应 Django 内置开发服务器。生产形态下Docker 镜像则通过 uWSGIdeploy/uwsgi.ini承载 WSGI 应用入口为 label_studio/core/wsgi.py。使用 Anaconda 安装如果你使用 conda 管理 Python 环境可以这样安装conda create --name label-studio conda activate label-studio pip install label-studio即在新建的 conda 环境中仍然通过 pip 安装 Label Studio 包这样既能隔离环境又能获得 PyPI 上的最新发布版本。升级 Label Studio使用 pip 升级到最新版pip install --upgrade label-studio升级后重启服务即可。服务启动时会自动检查并执行数据库迁移label_studio/server.py因此无需手工处理增量迁移。从 0.9.1 及更早版本升级到 1.0.0当从0.9.1 或更早版本升级到1.0.0时会触发迁移脚本用于把旧版项目数据迁移到新数据库。为确保已有项目被正确迁移启动时应显式指定旧项目路径label-studio start path/to/old/project从源码可以印证这条迁移链路label_studio/server.py 中start命令会检测指定路径下是否存在旧版config.json与config.xml若存在则调用 label_studio/core/old_ls_migration.py 中的migrate_existing_project完成项目迁移迁移完成后旧项目文件夹即可废弃。升级时的两个关键变化升级到 1.0.0 后需要重点关注以下两点字段重命名completions 被重命名为 annotations已完成任务的 JSON 导出格式随之变化详见 docs/source/guide/export.md 中的原始 JSON 格式说明前端定制兼容性如果你自定义过 Label Studio 前端需要参考 docs/source/guide/frontend_reference.md 进行必要的更新以保持与 1.0.0 的兼容。常见问题速查问题解决方案默认端口 8080 被占用使用label-studio start --port 新端口或设置LABEL_STUDIO_PORT环境变量源码层面还会自动探测空闲端口Docker 挂载目录无权限确保宿主机目录对容器内 UID 1001 可读写生产环境标注量很大从 SQLite 切换到 PostgreSQL见 docs/source/guide/storedata.md并保证内存 ≥ 16GB升级后旧项目数据消失用label-studio start path/to/old/project显式触发旧项目迁移离线服务器安装使用docker pulldocker savescpdocker image import离线搬运镜像小结Label Studio 提供了从个人开发到生产部署的完整安装矩阵本地快速上手推荐 pip 虚拟环境团队协作与生产环境推荐 Docker Compose PostgreSQL定制开发推荐源码安装。安装前重点核对 Python 版本3.10、8080 端口可用性、磁盘与内存预算以及挂载卷的 UID 1001 权限升级时则要留意 1.0.0 的 completions→annotations 重命名与前端兼容性要求。结合本文引用的 pyproject.toml、Dockerfile、docker-compose.yml 与 label_studio/server.py 源码你可以进一步深入理解每条安装路径背后的实现细节。【免费下载链接】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），仅供参考