pip 配置国内镜像源在 Mac 电脑安装 Label Studio 的详细教程

猫头虎

发布于 2025-06-08 09:08:51

68800

代码可运行

文章被收录于专栏：猫头虎博客专区猫头虎博客专区

运行总次数：0

代码可运行

pip 配置国内镜像源在 Mac 电脑安装 Label Studio 的详细教程

本文面向完全没有经验的初学者，详细讲解如何在 macOS（M 系列与 Intel 均适用）系统下，通过配置 pip 国内镜像源来加速并成功安装 Label Studio。全流程请按顺序阅读、操作，确保每一步都能顺利完成。

1. 什么是 Label Studio 及其安装难点

Label Studio 是一款由 Heartex 开发的开源数据标注与管理平台，支持图像、文本、音频、视频等多种数据类型的可视化标注。它广泛用于机器学习项目中数据预处理环节，具有灵活的标注界面、自定义插件与多种数据格式导入/导出能力。

主要功能：交互式标注、批量导入/导出、Web 界面管理、Python SDK 支持、与主流云存储集成等。
应用场景：图像分类、目标检测、语义分割、文本分类、实体识别、音频标注、视频关键帧标注等。

安装难点

下载速度慢：国内网络访问 PyPI 官方源时常因墙或带宽限制造成下载速度极慢，甚至失败。
依赖包体积大：Label Studio 依赖 Django、Pillow、numpy 等多个第三方包，其中一些可能需要编译安装。无镜像加速时会耗费大量时间。
SSL 证书验证：某些 macOS 默认 Python 证书链不全，可能导致 SSL: CERTIFICATE_VERIFY_FAILED 错误。
M 系列芯片兼容性：若你使用 Apple 提供的 M1/M2 芯片，部分 C 扩展包编译会出现“找不到架构”或“编译报错”问题，需要额外安装编译工具或指定环境变量。

因此，本文将从配置国内镜像源入手，大幅度提升 pip 安装速度，并结合 Mac 平台特性，保证 Label Studio 能顺利、快速地被安装到你当地的开发环境中。

公众号：猫头虎技术团队

2. 为何要配置 pip 国内镜像源

加速下载：官方 PyPI（https://pypi.org/simple/）在国内访问时往往速度很慢，甚至出现超时。国内镜像源（如阿里云、清华、中科大等）会定期同步官方仓库，速度更快、稳定性更好。
降低失败率：通过镜像源下载依赖包时，更少因网络波动导致下载中断或校验失败。
节约时间：安装 Label Studio 及其依赖时，往往会下载上百兆文件，使用镜像后可将下载时间从几十分钟缩短到几分钟以内。
命令兼容：镜像源与 pip 完全兼容，只需将 pip 的索引地址更换为镜像即可，不影响后续使用。

如果你在国内使用 macOS 安装 Python 包，强烈推荐全局配置 pip 镜像源，以便后续所有 pip 包的安装都能自动走镜像加速。
公众号：猫头虎技术团队

3. 环境准备：检查 macOS 与 Python 版本

在开始安装之前，建议先确认你的系统版本与 Python 版本，确保满足 Label Studio 的基本要求。

3.1. 检查 macOS 版本

点击屏幕左上角的苹果（）图标，选择“关于本机”（About This Mac）。
查看“macOS 版本”信息，例如：macOS Monterey 12.7、macOS Ventura 13.4 等。
如果 macOS 版本低于 11.0（Big Sur），建议先升级至至少 macOS 11 或更高，以获得更好的兼容性与安全补丁。

# 你也可以在终端执行以下命令查看：
sw_vers
# 示例输出：
# ProductName:	macOS
# ProductVersion:	13.4
# BuildVersion:	22F66

Label Studio 官方支持 Python 3.7 及以上版本，macOS 11+ 自带的 Python3 通常符合要求，但建议使用 Homebrew 安装的最新 Python3。

3.2. 检查 Python3 版本

macOS 自带一个系统级 Python3，但可能不是最新。为了避免权限冲突与系统依赖，我们推荐通过 Homebrew 安装 Python3。

在终端输入：

python3 --version
# 或者
which python3

如果输出 Python 3.9.x、3.10.x、3.11.x 等，即说明系统已有 Python3。
如果没有或版本过旧，可通过 Homebrew 进行升级（详见下文）。

确保你在后续配置的虚拟环境中使用的是你安装的 Python3，而非系统自带的 Python2。
公众号：猫头虎技术团队

4. 安装 Homebrew 及基础工具

本节将帮助你安装 Homebrew，以及通过 Homebrew 安装 Python3、Git 等常见开发工具，为后续安装 Label Studio 做准备。

4.1. 安装 Homebrew

Homebrew 是 macOS 上最受欢迎的包管理器，便于安装和管理各类开发工具。安装方法如下：

打开“终端”（Terminal）。

在终端中粘贴以下命令，按回车执行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装过程中，请按提示输入管理员密码，并按照脚本提示按“回车”继续。

安装完成后，根据终端提示，将 Homebrew 添加到 PATH 中：

# 以 zsh 为例，将以下内容复制到终端执行
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile

验证安装是否成功：

brew --version
# 正常情况下会输出类似：Homebrew 4.3.0

如果因网络原因下载缓慢，可临时使用代理，或参考Homebrew 中国镜像进行加速。

4.2. 安装 Python3（推荐使用 Homebrew）

虽然 macOS 自带 Python3，但为了获得最新版本与更好的隔离，推荐通过 Homebrew 安装：

brew update
brew install python@3.11

安装完成后，Homebrew 会在 /opt/homebrew/bin/python3（M 系列）或 /usr/local/bin/python3（Intel 系列）生成可执行文件。

验证 Python3 是否正确安装：

python3 --version
# 应输出：Python 3.11.x
which python3
# 应输出 Homebrew 安装路径，例如 /opt/homebrew/bin/python3

Homebrew 同时会安装对应的 pip3，你可以使用 pip3 --version 验证。

4.3. 配置虚拟环境（venv 或 pipenv）

为了避免与系统级 Python 依赖冲突，建议在项目目录下创建一个隔离的虚拟环境。以下示例以 python3 -m venv 为主，也提供 pipenv 方法供参考。

4.3.1. 方法一：使用 venv（Python 内置）

在你的工作目录下新建项目文件夹，例如 ~/projects/labelstudio_pip_mirror：

mkdir -p ~/projects/labelstudio_pip_mirror
cd ~/projects/labelstudio_pip_mirror

创建并激活虚拟环境：

python3 -m venv venv
source venv/bin/activate

激活后，终端提示符会出现 (venv)，表示处于该虚拟环境中。
若要退出环境，可执行 deactivate。

更新 pip、setuptools 及 wheel：

pip install --upgrade pip setuptools wheel

4.3.2. 方法二：使用 pipenv（可选）

安装 pipenv（全局）：

brew install pipenv

在项目文件夹中创建 pipenv 环境：

mkdir -p ~/projects/labelstudio_pip_mirror
cd ~/projects/labelstudio_pip_mirror
pipenv --python 3.11
pipenv shell

验证当前环境中 Python 与 pip 版本：

python --version   # 应该显示 Python 3.11.x
pip --version      # 对应 pip 21.x 及以上

提示：后续所有的 pip 安装命令都应在已激活的虚拟环境中执行，以保证依赖包都安装到该环境里。
公众号：猫头虎技术团队

5. 配置 pip 国内镜像源

本章重点介绍如何将 pip 默认源替换为国内镜像，包括常见的几类镜像源，以及临时与永久配置两种方式。

5.1. 常用国内镜像源介绍

以下为国内常见且更新及时的 PyPI 镜像源地址：（镜像列表不断更新，具体以镜像官方文档为准）

阿里云

https://mirrors.aliyun.com/pypi/simple/

清华大学

https://pypi.tuna.tsinghua.edu.cn/simple/

中国科学技术大学（中科大）

https://pypi.mirrors.ustc.edu.cn/simple/

华中理工大学（HUST）

https://mirrors.hust.edu.cn/pypi/web/simple/

豆瓣（douban）

https://pypi.douban.com/simple/

各镜像源同步频率略有差别，一般每小时或每日自动与官方同步一次。阿里云、清华、中科大常被推荐。

5.2. 方法一：临时使用镜像源（命令行参数）

如果你只想在某次安装时使用国内镜像，可在 pip install 命令后添加 -i 参数，示例：

# 临时使用清华镜像安装某个包
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ 包名

例如在虚拟环境中安装 Label Studio：

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

优点：操作非常简单，不会改动任何配置文件。
缺点：每次执行 pip install 都需要额外输入 -i 参数，容易忘记。

5.3. 方法二：全局配置 pip.conf

为了让后续所有 pip install 命令都自动使用镜像源，建议进行 全局配置。在 macOS 中，需要在用户主目录下为 pip 创建或修改 pip.conf 文件。

5.3.1. 针对 macOS 用户创建或修改配置文件

打开“终端”（Terminal），确保你处于主目录位置（~）：

cd ~

在主目录下创建 .pip 文件夹（若已存在可跳过）：

mkdir -p ~/.pip

在 .pip 文件夹下创建或打开 pip.conf（若已存在，则进行编辑）：

nano ~/.pip/pip.conf

这里使用 nano 作为文本编辑工具，你也可以使用 vim、code、TextEdit 等其他编辑器。

在 pip.conf 中添加以下内容（以清华镜像为例，可根据需要自行替换为阿里云、中科大等）：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
timeout = 6000

[install]
# 可选：指定下载缓存目录（默认 ~/.cache/pip）
# cache-dir = ~/.pip/cache

index-url：指定 pip 安装时使用的主索引源。
trusted-host：将镜像源域名加入为可信主机，避免 SSL 验证警告。
timeout：延长网络超时时间（单位秒），避免大包下载时因默认 15 秒超时导致失败。

保存并退出编辑器（在 nano 中按 Ctrl+O 保存，再按 Ctrl+X 退出）。

验证配置是否生效：

pip config list
# 输出应包含：
# global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
# global.trusted-host='pypi.tuna.tsinghua.edu.cn'
# global.timeout='6000'

完成上述配置后，你在任何地方执行 pip install <包名>，都会自动走清华镜像，而无需额外加 -i。公众号：猫头虎技术团队

6. 通过 pip 安装 Label Studio

在完成虚拟环境创建与 pip 镜像源配置后，即可快速、稳定地安装 Label Studio。

6.1. 激活虚拟环境

如果你使用的是 venv，在项目目录下执行：

cd ~/projects/labelstudio_pip_mirror
source venv/bin/activate

如果你使用的是 pipenv，执行：

cd ~/projects/labelstudio_pip_mirror
pipenv shell

激活后，终端提示符会显示当前环境名称（如 (venv) 或 (labelstudio_pip_mirror-xxxxx)），确认已进入对应环境。

6.2. 使用国内镜像源安装 Label Studio

确保你在激活的虚拟环境中，并且已经配置了全局的 pip 镜像源（如 5.3 节配置完成），直接执行：

pip install label-studio

pip 会自动从你在 pip.conf 中指定的镜像源下载所有依赖。
由于 Label Studio 依赖较多，整个过程可能会下载数百兆数据，但有镜像加速后大多数依赖包会在数秒或数十秒内完成。

若你希望在单次安装时显式指定镜像源（即使已全局配置），也可执行：

pip install -i https://mirrors.aliyun.com/pypi/simple/ label-studio

不同镜像源可替换 -i 后面的 URL。

6.3. 验证安装结果

安装完成后，可以通过以下命令查看 Label Studio 版本，验证是否安装成功：

label-studio --version
# 预期输出：
# label-studio, version 1.x.x

在当前目录生成 Label Studio 项目数据目录（可选）：

label-studio init

该命令会在当前路径下生成一个 label_studio_data 文件夹，里面包含默认的 SQLite 数据库、静态文件、模板等。

启动 Label Studio 服务（默认端口 8080）：

label-studio start --port 8080

启动成功后，终端会输出类似：

Starting Label Studio at: http://localhost:8080

在浏览器中打开 http://localhost:8080，如下图所示，你将看到 Label Studio 的登录/注册页面。

如果浏览器中无法访问，请检查防火墙设置或是否有其它程序占用 8080 端口。可通过 label-studio start --port 9000 切换端口。
公众号：猫头虎技术团队

7. 常见问题与解决方案

即使配置了国内镜像源，也可能在安装和使用过程中出现一些常见问题。下面一一罗列并给出解决方法。

7.1. “pip 安装速度依然很慢”

症状：即便已经全局配置了清华/阿里云镜像，执行 pip install label-studio 时，下载速度依然很慢，或出现大量超时重试。

可能原因：

网络环境不佳，比如 Wi-Fi 信号弱、运营商 DNS 解析慢。
某些依赖包在镜像源上同步滞后，需要回退到官方源临时下载。
你的 pip 版本过旧，未正确读取 pip.conf 配置。

解决方案：

确认你的 pip 版本是否较新：

pip --version
# 建议 pip 版本 >= 20.x

如果镜像源同步滞后，可在单次安装时指定多个索引，例如：

pip install \
  -i https://pypi.tuna.tsinghua.edu.cn/simple/ \
  --extra-index-url https://pypi.org/simple \
  label-studio

这样若镜像源上没有最新包，就会自动从官方源拉取。

检查网络：尝试切换到有线网络或更稳定的 VPN，再次执行安装。

手动升级 pip：

pip install --upgrade pip

临时把系统 DNS 改为公共 DNS（如 114.114.114.114 或 8.8.8.8），然后再试。

7.2. “依赖包编译失败”

症状：在下载并解压某些包后（如 Pillow、psycopg2、mysqlclient、opencv-python 等），出现编译报错、缺少头文件或库文件等。

可能原因：

机器缺少开发工具链（Xcode Command Line Tools、C 编译器）。
某些依赖包需要系统级依赖库（如 libjpeg、zlib、freetype、postgresql-client）。
M 系列芯片下，未正确指定环境变量或未安装 Rosetta 2（x86 软件需要的情况下）。

解决方案：

安装 Xcode Command Line Tools（如果未安装）：

xcode-select --install

安装常见系统库（以 Homebrew 为例）：

brew install libjpeg libpng zlib freetype
brew install postgresql     # 如果需要安装 psycopg2 或 mysqlclient
brew install mysql-client    # 或者安装 MySQL 客户端

指定环境变量，让编译器能找到 Homebrew 库：

export LDFLAGS="-L/opt/homebrew/lib"
export CPPFLAGS="-I/opt/homebrew/include"
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig"

如果你使用 Intel Mac，则把 /opt/homebrew 改为 /usr/local。

若在 M 系列需要使用 x86 环境, 可安装 Rosetta 2 并运行某些命令于 x86 模式下：

/usr/sbin/softwareupdate --install-rosetta --agree-to-license

然后在编译包前，使用：

arch -x86_64 pip install Pillow

或者在整个虚拟环境中都使用 x86 架构：

arch -x86_64 /bin/bash
source venv/bin/activate
pip install label-studio

如果你并不需要使用某些可选依赖（如 PostgreSQL 支持），可先跳过相关包的安装，后续再单独安装。

7.3. “label-studio 命令未找到”

症状：激活虚拟环境后执行 label-studio --version 报 command not found 或者类似 No module named 'label_studio'。

可能原因：

你当前所在的 shell 并未激活虚拟环境。
pip install label-studio 安装在了全局 Python，而非虚拟环境。
系统 PATH 中没有包含虚拟环境的 bin 目录。

解决方案：

确保虚拟环境已正确激活：

source ~/projects/labelstudio_pip_mirror/venv/bin/activate

激活后，终端提示符前会出现 (venv)。

在激活环境后，再次执行安装：

pip install label-studio

执行 which label-studio，应输出类似：

/Users/yourname/projects/labelstudio_pip_mirror/venv/bin/label-studio

如果仍然找不到，可尝试指定 Python 执行路径：

python3 -m label_studio --version

若此条命令能够输出版本号，则说明安装成功，但 PATH 未生效，可在 ~/.zshrc 或 ~/.bash_profile 中添加：

export PATH="$HOME/projects/labelstudio_pip_mirror/venv/bin:$PATH"

然后执行 source ~/.zshrc 或相应配置文件，使其生效。

7.4. “SSL 证书验证失败”

症状：在执行 pip install 时，报错 SSL: CERTIFICATE_VERIFY_FAILED，提示无法验证 HTTPS 连接。

可能原因：

系统缺少根证书或证书链未正确配置。
镜像源地址未被列为 Trust Host。

解决方案：

在 pip.conf 中添加 trusted-host 配置（已在 5.3 节示例中添加）。

手动更新系统证书：

/Applications/Python\ 3.11/Install\ Certificates.command

上述命令会为 Homebrew 安装的 Python3 更新证书链。
如果你安装了多个 Python 版本，请根据实际路径执行对应的 Install Certificates.command。

如仍然报错，可临时添加 --trusted-host 参数：

pip install --trusted-host pypi.tuna.tsinghua.edu.cn \
    -i https://pypi.tuna.tsinghua.edu.cn/simple/ label-studio

完成上述步骤后，SSL 验证失败的问公众号：猫头虎技术团队

8. 附加：使用 Docker 安装 Label Studio（可选）

如果你熟悉 Docker，并希望将 Label Studio 部署到容器中，也可以通过 Docker 来安装。即使针对国内用户，也同样需要配置 Docker 镜像加速（例如阿里云、DaoCloud 等），以便快速拉取官方镜像或构建自定义镜像。

8.1. 为什么在国内也要配置 Docker 镜像加速

拉取官方镜像速度慢：默认 docker pull heartexlabs/label-studio:latest 在国内网络环境下常常需要十几分钟甚至更长时间。
减少失败率：通过国内镜像加速地址，可以大幅降低下载中断或网络超时的概率。

常见的 Docker 加速器地址示例：

阿里云 Docker 加速器：https://<你的加速器 ID>.mirror.aliyuncs.com
DaoCloud：http://f1361db2.m.daocloud.io
网易云镜像：hub-mirror.c.163.com
Azure 中国：https://dockerhub.azk8s.cn

配置方法可参照相应平台说明，将加速器地址填入 ~/.docker/daemon.json 文件中。

8.2. Docker 安装简要步骤

下载并安装 Docker Desktop for Mac（Apple Silicon 或 Intel 版）

前往 Docker 官网下载对应版本并安装。
打开 Docker Desktop，确保其运行正常，并且在“Preferences → Resources”中为 Docker 分配足够的 CPU 与内存（至少 2 CPU、4GB 内存）。

配置 Docker 镜像加速（可选，但强烈推荐）

打开终端，编辑或创建 Docker 配置文件 /etc/docker/daemon.json：

sudo mkdir -p /etc/docker
sudo nano /etc/docker/daemon.json

在 daemon.json 中添加以下内容（以阿里云加速器为例，请替换为你自己的加速器地址）：

{
  "registry-mirrors": [
    "https://<你的加速器 ID>.mirror.aliyuncs.com"
  ]
}

保存并退出后，重启 Docker Desktop，即可生效。

拉取官方 Label Studio 镜像

M 系列 Apple Silicon 用户：默认镜像为 x86 架构，需要加 --platform linux/amd64 强制拉取并通过 Rosetta 翻译运行，或自行构建 ARM 镜像。
Intel 用户：直接拉取即可。

示例（Intel 或通过 Rosetta 的 M 系列）：

docker pull --platform linux/amd64 heartexlabs/label-studio:latest

运行容器

使用官方镜像启动容器，并将本地目录映射到容器：

docker run -d \
  --name label-studio-container \
  -p 8080:8080 \
  -v ~/projects/labelstudio_pip_mirror/label_studio_data:/label-studio/data \
  --platform linux/amd64 \
  heartexlabs/label-studio:latest

-d：后台运行容器
-p 8080:8080：将本机 8080 端口映射到容器 8080
-v 本地路径:容器路径：挂载卷以便持久化数据
--platform linux/amd64：在 M 系列上强制拉取并使用 x86 镜像（依赖 Rosetta 2）

Intel 用户可省略 --platform 参数：

docker run -d \
  --name label-studio-container \
  -p 8080:8080 \
  -v ~/projects/labelstudio_pip_mirror/label_studio_data:/label-studio/data \
  heartexlabs/label-studio:latest

访问 Label Studio

打开浏览器，访问 http://localhost:8080 即可进入 Label Studio 登录/注册页面。

如果需要查看容器日志，可执行：