zzreo
← 全部文章

pyenv 常用命令手册

本文目录
  1. 1. pyenv 是什么
  2. 2. 适合什么场景
  3. 3. 常用命令
    1. 查看 pyenv 状态
    2. 查看可安装版本
    3. 安装 Python
    4. 设置全局版本
    5. 设置当前目录版本
    6. 临时设置当前 shell 版本
    7. 卸载 Python 版本
    8. 重新生成 shim
  4. 4. 常见工作流
    1. 给新项目指定 Python 版本
    2. 查看当前项目到底用了哪个 Python
    3. 切回默认版本
  5. 5. 常见目录
  6. 6. 你最常用的几条
  7. 7. 注意事项

1. pyenv 是什么

pyenv 是一个 Python 版本管理工具,主要用来:

  • 在一台电脑上安装多个 Python 版本
  • 在不同项目之间切换不同的 Python 版本
  • 避免系统自带 Python 和项目 Python 互相污染

它本身不负责包管理,主要职责是 管理 Python 解释器版本。


2. 适合什么场景

  • 你同时维护 Python 3.9 / 3.10 / 3.11 / 3.12
  • 某些老项目只能用特定 Python 版本
  • 你不想污染系统 Python
  • 你要给不同项目隔离解释器

3. 常用命令

查看 pyenv 状态

pyenv --version
pyenv versions
pyenv version
pyenv which python

说明:

  • pyenv versions:查看已安装的 Python 版本
  • pyenv version:查看当前生效的版本
  • pyenv which python:查看当前 python 实际指向哪里

查看可安装版本

pyenv install --list
pyenv install --list | grep 3.11

说明:

  • 第一条会列出所有可安装版本
  • 第二条可以筛选你要的版本号

安装 Python

pyenv install 3.11.9
pyenv install 3.12.4

说明:

  • 安装完成后,可以用 pyenv versions 查看

设置全局版本

pyenv global 3.11.9

说明:

  • 设置当前用户默认 Python 版本
  • 新开终端后通常也会生效

设置当前目录版本

pyenv local 3.12.4

说明:

  • 会在当前目录生成一个 .python-version
  • 进入这个项目目录时,自动切换到指定 Python 版本

临时设置当前 shell 版本

pyenv shell 3.11.9

说明:

  • 只对当前终端会话生效
  • 关闭终端后失效

卸载 Python 版本

pyenv uninstall 3.11.9

说明:

  • 删除某个已安装版本
  • 删除前先确认没有项目依赖它

重新生成 shim

pyenv rehash

说明:

  • 当你安装了新的可执行工具后,常用它刷新命令映射

4. 常见工作流

给新项目指定 Python 版本

cd your-project
pyenv install 3.11.9
pyenv local 3.11.9
python --version

查看当前项目到底用了哪个 Python

pyenv version
pyenv which python
python --version

切回默认版本

pyenv global 3.11.9

如果之前在项目里执行过 pyenv local,想取消目录级绑定,可以删除:

rm .python-version

5. 常见目录

~/.pyenv

常见内容:

  • ~/.pyenv/versions:安装的 Python 版本
  • ~/.pyenv/shims:命令 shim
  • ~/.pyenv/version:全局默认版本

6. 你最常用的几条

pyenv versions
pyenv install 3.11.9
pyenv global 3.11.9
pyenv local 3.11.9
pyenv version
pyenv which python
pyenv uninstall 3.11.9

7. 注意事项

  • pyenv 管的是 Python 版本,不是 pip 依赖隔离
  • 真正做项目隔离时,通常还会配合 venv 或 virtualenv
  • 如果 python --version 和你预期不一致,先检查:
pyenv version
pyenv which python
echo $PATH