GitLab CI中pip安装Streamlit 1.10.0报UnicodeEncodeError如何解决

开发者阿泽

2026-8-29

问题描述

在GitLab CI环境下，将streamlit升级到1.10.0版本后，执行pip install streamlit命令安装时抛出编码异常，核心报错信息如下：

ERROR: Exception:
Traceback (most recent call last):
  File "/builds/project/venv/lib/python3.6/site-packages/pip/_internal/cli/base_command.py", line 164, in exc_logging_wrapper
    status = run_func(*args)
  File "/builds/project/venv/lib/python3.6/site-packages/pip/_internal/cli/req_command.py", line 205, in wrapper
    return func(self, options, args)
  File "/builds/project/venv/lib/python3.6/site-packages/pip/_internal/commands/install.py", line 413, in run
    pycompile=options.compile,
  File "/builds/lproject/venv/lib/python3.6/site-packages/pip/_internal/req/__init__.py", line 81, in install_given_reqs
    pycompile=pycompile,
  File "/builds/project/venv/lib/python3.6/site-packages/pip/_internal/req/req_install.py", line 810, in install
    requested=self.user_supplied,
  File "/builds/project/venv/lib/python3.6/site-packages/pip/_internal/operations/install/wheel.py", line 737, in install_wheel
    requested=requested,
  File "/builds/project/venv/lib/python3.6/site-packages/pip/_internal/operations/install/wheel.py", line 589, in _install_wheel
    file.save()
  File "/builds/project/venv/lib/python3.6/site-packages/pip/_internal/operations/install/wheel.py", line 383, in save
    if os.path.exists(self.dest_path):
  File "/builds/project/venv/lib/python3.6/genericpath.py", line 19, in exists
    os.stat(path)
UnicodeEncodeError: 'ascii' codec can't encode character '\U0001f4f9' in position 76: ordinal not in range(128)

经排查，报错中无法被ASCII编码的字符为摄像机emoji 📹，对应编码为\U0001f4f9。

根因分析

该问题由两个条件共同触发：

streamlit 1.10.0版本的安装包内，存在文件名包含上述emoji的静态资源文件；
当前运行环境使用Python 3.6版本，且GitLab CI运行环境默认未配置UTF-8编码参数，Python 3.6处理文件系统路径时默认回退到ASCII编码，遇到emoji这类超出ASCII范围的字符就会抛出编码错误。

可行解决方案

按推荐优先级排序，任选其一即可解决：

升级运行环境的Python版本到3.7及以上。Python 3.7版本开始将文件系统默认编码调整为UTF-8，原生支持emoji等非ASCII字符路径，可彻底规避这类编码问题，是长期维护的最优选择。

在GitLab CI任务执行前显式配置UTF-8环境变量，无需改动Python或依赖版本，改动成本最低。配置示例：

before_script:
  - export LC_ALL=C.UTF-8
  - export LANG=C.UTF-8
  # 后续再执行依赖安装命令
  - pip install streamlit==1.10.0

若暂时无法调整Python版本、也不方便修改CI全局配置，可先将pip升级到最新版本再尝试安装，旧版本pip的路径编码处理逻辑存在已知缺陷，部分场景下升级后即可兼容非ASCII路径：
```
pip install --upgrade pip
pip install streamlit==1.10.0
```
以上方案都无法落地时，可临时降级streamlit到1.10.0之前的版本（比如1.9.0），这些版本的包内没有带emoji的文件名，不会触发该编码错误：
```
pip install streamlit==1.9.0
```

内容的提问来源于stack exchange，提问作者vvvvv