Ubuntu 24.04虚拟环境中pip安装pygame失败求助

问题描述 #

在Ubuntu 24.04系统的Python 3.12.3虚拟环境（venv）中执行pip install pygame时失败，错误提示找不到sdl2-config、pkg-config、freetype-config工具，要求安装SDL开发版本。

解决方案 #

1. 安装系统依赖包

错误核心是缺少pygame编译所需的系统开发库和配置工具，通过apt安装以下包即可解决：

sudo apt update
sudo apt install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev pkg-config libfreetype6-dev

这些包包含了缺失的sdl2-config、pkg-config、freetype-config工具，以及pygame依赖的SDL系列开发库。

2. 重新安装pygame

激活你的虚拟环境后，再次执行pip安装：

# 激活虚拟环境
source /home/salvadorduran/Documents/Projects/musicplayer/mpEnv/bin/activate
# 安装pygame
pip install pygame

3. 可选：使用预编译wheel跳过编译

如果编译仍然有问题，可以强制使用预编译的wheel包，避免本地编译过程：

pip install pygame --only-binary :all:

完整错误日志 #

$ pip install pygame
Collecting pygame
  Using cached pygame-2.6.0.tar.gz (15.8 MB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  error: subprocess-exited-with-error
  
  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [53 lines of output]
      Skipping Cython compilation
      
      
      WARNING, No "Setup" File Exists, Running "buildconfig/config.py"
      Using UNIX configuration...
      
      /bin/sh: 1: sdl2-config: not found
      /bin/sh: 1: sdl2-config: not found
      /bin/sh: 1: sdl2-config: not found
      /bin/sh: 1: pkg-config: not found
      /bin/sh: 1: pkg-config: not found
      /bin/sh: 1: pkg-config: not found
      /bin/sh: 1: freetype-config: not found
      /bin/sh: 1: freetype-config: not found
      /bin/sh: 1: freetype-config: not found
      
      Hunting dependencies...
      WARNING: "sdl2-config" failed!
      WARNING: "pkg-config freetype2" failed!
      WARNING: "freetype-config" failed!
      
      ---
      For help with compilation see:
          https://www.pygame.org/wiki/Compilation
      To contribute to pygame development see:
          https://www.pygame.org/contribute.html
      ---
      
      Traceback (most recent call last):
        File "/home/salvadorduran/Documents/Projects/musicplayer/mpEnv/lib/python3.12/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
          main()
        File "/home/salvadorduran/Documents/Projects/musicplayer/mpEnv/lib/python3.12/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 335, in main
          json_out['return_val'] = hook(**hook_input['kwargs'])
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/home/salvadorduran/Documents/Projects/musicplayer/mpEnv/lib/python3.12/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 118, in get_requires_for_build_wheel
          return hook(config_settings)
                 ^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-1fn_8yi6/overlay/lib/python3.12/site-packages/setuptools/build_meta.py", line 327, in get_requires_for_build_wheel
          return self._get_build_requires(config_settings, requirements=[])
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-1fn_8yi6/overlay/lib/python3.12/site-packages/setuptools/build_meta.py", line 297, in _get_build_requires
          self.run_setup()
        File "/tmp/pip-build-env-1fn_8yi6/overlay/lib/python3.12/site-packages/setuptools/build_meta.py", line 497, in run_setup
          super().run_setup(setup_script=setup_script)
        File "/tmp/pip-build-env-1fn_8yi6/overlay/lib/python3.12/site-packages/setuptools/build_meta.py", line 313, in run_setup
          exec(code, locals())
        File "<string>", line 426, in <module>
        File "/tmp/pip-install-o7k2dau0/pygame_136947bea63141b1b724389631340fca/buildconfig/config.py", line 234, in main
          deps = CFG.main(**kwds, auto_config=auto)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-install-o7k2dau0/pygame_136947bea63141b1b724389631340fca/buildconfig/config_unix.py", line 245, in main
          raise RuntimeError('Unable to run "sdl-config". Please make sure a development version of SDL is installed.')
      RuntimeError: Unable to run "sdl-config". Please make sure a development version of SDL is installed.
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: subprocess-exited-with-error

× Getting requirements to build wheel did not run successfully.
│ exit code: 1
╰─> See above for output.

note: This error originates from a subprocess, and is likely not a problem with pip.

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