pyenv-virtualenv是pyenv的插件，非独立工具；装好pyenv后通常已自带，无需pip install，但需执行eval "$(pyenv virtualenv-init -)"并确保pyenv shims在PATH最前，且Python版本须预先安装。
pyenv 和 pyenv-virtualenv 不是两个独立安装的工具，后者是前者的插件——**装好 pyenv 后，pyenv-virtualenv 通常已自带，无需单独 pip install**。这是最容易踩的第一个坑：很多人反复执行 pip install pyenv-virtualenv，结果发现 pyenv virtualenv 命令仍报错或不识别。
确认 pyenv 是否已带 virtualenv 插件
运行以下命令：
pyenv commands | grep virtualenv
如果输出包含 virtualenv、virtualenv-delete、virtualenvs，说明插件已就绪；否则需检查安装方式。
- 用
pyenv-installer脚本安装（推荐）：自动包含pyenv-virtualenv - 手动 git clone 安装：需额外执行
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv - Mac 上用
brew install pyenv pyenv-virtualenv：二者会同时装上，但注意brew版本可能滞后
配置必须加这行，否则 virtualenv 命令无效
立即学习“Python免费学习笔记（深入）”；
很多用户配好了 pyenv，却漏掉关键一行：
eval "$(pyenv virtualenv-init -)"
它必须和 pyenv init 一起写进 ~/.bashrc 或 ~/.zshrc，顺序无关，但缺一不可。漏掉后，pyenv virtualenv 3.9.18 myproject 会静默失败，或者提示 command not found: pyenv-virtualenv。
创建虚拟环境时，Python 版本必须已安装且可用
pyenv virtualenv 不会自动帮你装 Python。执行前请确认：
-
pyenv install -l | grep 3.9.18能查到该版本（说明源里有） -
pyenv install 3.9.18已成功执行（编译完成，无 error） -
pyenv versions输出中包含3.9.18（前面没星号也行，只要存在）
常见错误：pyenv virtualenv 3.9.18 myproj 报错 python-build: definition not found: 3.9.18，本质是版本没装，不是命令写错。
虚拟环境名不能和已存在目录同名，也不能含斜杠
pyenv virtualenv 会在 $(pyenv root)/versions/ 下建子目录，例如：
~/.pyenv/versions/3.9.18/envs/myproj
所以：
- 如果当前目录下已有
myproj/文件夹，命令会失败（提示 directory not empty） -
pyenv virtualenv 3.9.18 myproj/sub是非法的——名字里不能含/ - 名字区分大小写，
MyProj和myproj是两个环境
激活方式不是 source myproj/bin/activate，而是统一走 pyenv 调度：
-
pyenv local myproj（只对当前目录生效） -
pyenv shell myproj（只对当前 shell 会话生效） -
pyenv global myproj（全局默认，慎用）
执行后，which python 会指向 ~/.pyenv/versions/myproj/bin/python，而不是系统或 pyenv 版本路径。
真正容易被忽略的是：pyenv 的 shims 机制依赖 PATH 中 $(pyenv root)/shims 在最左侧。一旦你手动改过 PATH（比如在脚本里 export PATH=/usr/local/bin:$PATH），就可能把 shims 排到后面，导致 python 命令绕过 pyenv 直接调用系统 Python。这种问题不会报错，只会“看起来一切正常，但实际没切版本”。
