如何在 Mac 的 VS Code 中安装 pygame 并解决导入报错？

2026-11-04排障赵师傅

可以继续使用 VS Code。ModuleNotFoundError: No module named 'pygame' 表示运行程序的 Python 找不到 pygame。先检查安装 pygame 和运行程序时用的是不是同一个 Python 环境。

venv 是 Python 的虚拟环境，Windows 和 macOS 都能使用。它为项目单独保存第三方包，避免不同项目的依赖互相影响。两个系统的目录结构和激活命令有所不同。

为什么能看到 pygame 文件夹，仍然无法导入？

一台 Mac 上可能同时装有多个 Python，例如独立安装的 Python、Homebrew 安装的 Python，以及项目虚拟环境中的 Python。

如果 pip 把 pygame 安装到了一个环境，而 VS Code 用另一个环境运行程序，就会出现这个错误。即使磁盘上有 pygame 文件夹，运行程序的解释器也未必能找到它。

先在出错程序的最前面加上：

import sys

print(sys.executable, flush=True)

import pygame

打印出的路径就是运行该程序的 Python 解释器路径。安装 pygame 时也应使用这个解释器。

在项目虚拟环境中安装 pygame

1. 确认 Python 可以运行

在 VS Code 中打开项目文件夹，再打开集成终端，执行：

python3 --version

如果提示找不到命令，需要先安装 Python 3。可以使用 Python 官网提供的 macOS 安装程序，安装后重新打开终端，再检查一次。

VS Code 的 Python 扩展和 Python 解释器需要分别安装，只装扩展还不能运行 Python 程序。

2. 创建环境并安装 pygame

在项目根目录执行：

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install pygame

指定 .venv/bin/python 后，安装命令就会使用项目环境中的 Python。-m pip 调用的是这个解释器对应的 pip，可以避免单独执行 pip 时选错环境。

如果已经创建了名为 venv 的环境，可以继续使用，把命令中的 .venv 换成 venv 即可，不用再创建一个。

安装完成后，运行以下命令验证：

.venv/bin/python -c "import sys; import pygame; print(sys.executable); print(pygame.__file__)"

如果命令执行成功，并显示 pygame 的文件路径，就说明这个虚拟环境可以导入 pygame。

让 VS Code 使用这个环境

在 VS Code 的扩展面板中安装 Microsoft 发布的 Python 扩展，然后：

按 Command + Shift + P 打开命令面板。
执行 Python: Select Interpreter。
选择项目中的 .venv/bin/python。
如果列表中没有该环境，通过输入解释器路径的选项手动定位。

打开 Python 文件，在命令面板中执行 Python: Run Python File in Terminal。查看前面打印的 sys.executable，确认它指向项目虚拟环境。

已有终端可能还在使用之前的环境。如果想在终端直接输入 python 来运行程序，可以新建终端，再手动激活环境：

source .venv/bin/activate
python -m pip show pygame
python main.py

把 main.py 换成你的文件名。激活环境会调整当前终端的命令搜索路径。如果使用完整的 .venv/bin/python 路径，就不需要先激活。

Windows 上常见的 venv\Scripts\activate 和 macOS 上的 source .venv/bin/activate 作用相近，分别适用于不同的目录结构和 shell。

用一个小程序验证

将下面的代码保存为 main.py，不要命名为 pygame.py：

import pygame

pygame.init()

screen = pygame.display.set_mode((640, 480))
pygame.display.set_caption("pygame test")
clock = pygame.time.Clock()

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    screen.fill((30, 30, 30))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

从项目根目录运行：

.venv/bin/python main.py

如果窗口能打开并正常关闭，就说明这个环境中的 pygame 可以完成基本的窗口初始化和事件处理。

仍然报错时，按现象排查

终端能运行，VS Code 的运行按钮报错

再次检查出错程序打印的 sys.executable。

如果使用的是 Code Runner 扩展的 Run Code，它可能会按自己的配置选择 Python。先用 Python 扩展提供的 Python: Run Python File in Terminal 验证。如果调试时的结果不同，还要检查 .vscode/launch.json 是否单独指定了解释器。

pip 显示已安装，程序仍然找不到

用运行程序的那个解释器查询安装位置：

.venv/bin/python -m pip --version
.venv/bin/python -m pip show pygame

如果第二条命令提示找不到包，就在这个环境中重新安装：

.venv/bin/python -m pip install pygame

另一个终端中的 pip install 输出未必能反映当前环境的安装状态。也不要手动把 pygame 文件夹复制到项目中。

安装命令本身失败

遇到 No matching distribution found、编译失败或缺少依赖等问题，需要结合完整的安装日志判断原因，不能一概归因于 VS Code。

pygame 的安装包是否可用，取决于 Python 版本、macOS 版本和处理器架构等条件。Mac Mini 既有 Intel 机型，也有 Apple Silicon 机型。先确认这些信息，再选择对应架构的安装教程。

保留完整日志，先查看 pip 最早报告的具体错误。不要为了绕过错误直接执行 sudo pip install pygame，也不要急着添加一长串编译依赖。

是否需要改用 Wing？

可以按编辑习惯选择 Wing，不过更换编辑器后仍然需要配置 Python 环境。安装 pygame 和运行代码使用同一个解释器，VS Code 就可以用于这个项目。

处理当前错误时，先确认虚拟环境能导入 pygame，再让 VS Code 使用同一个解释器，通常比重新安装编辑器更直接。