VS Code .venv环境pip安装依赖报wcwidth无效wheel错误如何解决

运行环境为VS Code绑定的.venv虚拟环境，Python版本3.8.0，执行pip install -r requirements.txt安装项目依赖时出现以下报错：

ERROR: wcwidth has an invalid wheel, wcwidth has an invalid wheel, multiple .dist-info directories found: wcwidth-0.2.1.dist-info, wcwidth-0.2.0.dist-info

本次安装使用的requirements.txt依赖清单如下：

adal==1.2.7
argcomplete==1.12.3
azure-common==1.1.27
azure-core==1.20.1
azure-graphrbac==0.61.1
azure-identity
azure-mgmt-authorization==0.61.0
azure-mgmt-containerregistry==8.2.0
azure-mgmt-core==1.3.0
azure-mgmt-keyvault==9.3.0
azure-mgmt-resource==19.0.0
azure-mgmt-storage==19.0.0
azure-storage-blob==12.9.0
azureml-core==1.37.0.post1
backports.tempfile==1.0
backports.weakref==1.0.post1
bcrypt==3.2.0
certifi==2021.10.8
cffi==1.15.0
charset-normalizer==2.0.9
click==8.0.3
colorama==0.4.4
contextlib2==21.6.0
cryptography==3.4.8
cycler==0.11.0
docker==5.0.3
et-xmlfile==1.1.0
fonttools==4.28.3
humanfriendly==9.2
idna==3.3
importlib-metadata==4.8.2
isodate==0.6.0
jeepney==0.7.1
jmespath==0.10.0
joblib==1.1.0
jsonpickle==2.0.0
kiwisolver==1.3.2
knack==0.8.2
matplotlib==3.4.0
msal==1.16.0
msal-extensions==0.3.1
msrest==0.6.21
msrestazure==0.6.4
mypy-extensions==0.4.3
mlflow==1.22.0
azureml-mlflow==1.37.0
ndg-httpsclient==0.5.1
numpy==1.18.1
oauthlib==3.1.1
openpyxl==3.0.9
packaging==21.3
pandas==1.3.5
paramiko==2.8.1
pathspec==0.9.0
Pillow==8.4.0
pkginfo==1.8.2
platformdirs==2.4.0
portalocker==2.3.2
pyasn1==0.4.8
pycodestyle==2.8.0
pycparser==2.21
Pygments==2.10.0
PyJWT==2.3.0
PyNaCl==1.4.0
pyodbc==4.0.32
pyOpenSSL==21.0.0
pyparsing==3.0.6
pyreadline==2.1
PySocks==1.7.1
python-dateutil==2.8.2
pytz==2021.3
PyYAML==6.0
requests==2.26.0
requests-oauthlib==1.3.0
scikit-learn==0.22.1
scipy==1.4.1
SecretStorage==3.3.1
setuptools-scm==6.3.2
six==1.16.0
sklearn==0.0.0
tabulate==0.8.9
threadpoolctl==3.0.0
toml==0.10.2
tomli==1.2.2
typed-ast==1.5.1
typing_extensions==4.0.1
urllib3==1.26.7
websocket-client==1.2.3
yapf==0.31.0
zipp==3.6.0
pyspark==3.2.0
python-dotenv==0.12.*
statsmodels==0.11.0
pytest==5.4.*
pytest-cov==2.8.*
azureml-pipeline==1.37.0
pydantic
ppgamlutils
ppgmlframework

虚拟环境的site-packages路径下残留了两个不同版本wcwidth的dist-info元数据目录，pip校验安装包时检测到元数据冲突，判定wcwidth的wheel包无效。该问题一般由之前安装/升级wcwidth时进程中断、pip本地缓存损坏导致。

按顺序执行以下操作即可修复：

• 清理本地pip缓存，执行命令：
  pip cache purge
• 进入虚拟环境的site-packages目录，删除所有名称带wcwidth的文件夹：
  • Windows系统路径为.venv/Lib/site-packages/
  • macOS/Linux系统路径为.venv/lib/python3.8/site-packages/
    要删除的内容包括报错提到的wcwidth-0.2.0.dist-info、wcwidth-0.2.1.dist-info，以及wcwidth的源码目录。
• 单独安装兼容版本的wcwidth，避免依赖解析时拉取损坏的包：
  pip install wcwidth==0.2.1
• 验证wcwidth安装无报错后，重新执行依赖安装命令：
  pip install -r requirements.txt

如果上述操作后仍存在报错，直接重建干净虚拟环境即可彻底解决残留问题：

# 退出当前虚拟环境
deactivate
# 删除旧虚拟环境目录（Windows执行第一行，macOS/Linux执行第二行）
rmdir /s /q .venv
rm -rf .venv
# 重新创建虚拟环境
python -m venv .venv
# 激活新虚拟环境后重新安装依赖
pip install -r requirements.txt

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