[Python] Pygame 모듈이 설치되지 않는 문제 해결 방법(VSCode 우분투)

Pygame 모듈을 사용하여 게임 프로그래밍 코드을 작성하던 중, 모듈이 설치되어 있지 않다는 오류가 발생하여 문제를 해결하느라 몇시간동안 끙끙 앓았다 😭

>>> python -u "/mnt/c/Users/유저명/OneDrive/문서/Coding/폴더명1/폴더명2/폴더명3/폴더명4/파일명.py"
Traceback (most recent call last):
  File "/mnt/c/Users/유저명/OneDrive/문서/Coding/폴더명1/폴더명2/폴더명3/폴더명4/파일명.py", line 1, in <module>
    import pygame
ModuleNotFoundError: No module named 'pygame'

분명 pip3 install pygame 까지 했고 터미널에 python3와 import pygame으로 실행까지 되는 걸 확인했는데 왜 안되는건지!

인터넷에 온갖 다 뒤져보았다. sudo -H pip3 install pygame도 해보았고 pip3 install pygame --pre 도 해보았는데도 해결할 기미가 안보이고 다음날 되서야 해결이 되었다. 해결 방법은 다음과 같다.

1. Python 버전 다운그레이드

기존에 사용하던 Python 3.11 버전에서 Pygame 모듈이 정상적으로 동작하지 않는 것 같다. 아마 내가 자세히 못찾은 걸 수도 있겠지만, Pygame의 공식 홈페이지나 문서(Pygame 공식 문서: https://www.pygame.org/news)에서는 파이썬 3.11과의 호환성에 대한 언급이 없는 것 같다, 그리고 Pygame의 GitHub 저장소(Pygame GitHub 페이지: https://github.com/pygame/pygame)에서도 최근 3.11 버전에서의 호환성에 대한 이슈가 제기되고 있는 것 같았다. 물론 나중에 언젠가는 Pygame 개발자들이 해결해서 파이썬 3.11도 호환되도록 해주시겠지..:)

따라서 나는 파이썬 3.10으로 다운그레이드 하기로 결심했다.

일단 현재 버전인 3.11을 지웠다.

파이썬 3.11 제거

>>> sudo apt-get remove python3.11

그리고 파이썬 3.10을 설치했다. 설치한 뒤, python3.10 -V로 3.10이 설치가 되었는지 확인하기 위해 버전 체크를 했고 pip3 -V를 입력해서 현재 pip와 파이썬간의 버전이 호환되는지도 확인했다.

파이썬 3.10 설치 및 버전 확인

>>> sudo apt-get install python3.10
>>> python3.10 -V
Python 3.10.6
>>> pip3 -V
pip 23.0.1 from /usr/local/lib/python3.10/dist-packages/pip (python 3.10)

Python 3.10을 기본적으로 사용하기 위해 'sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1' 명령어를 입력했다.
그러고 나서 'python3 -V'으로 3.10이 기본적으로 사용이 됬는지 확인을 했더니 잘 적용된 것 같았다.

파이썬 3.10을 default로

>>> sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1
>>> python3 -V
Python 3.10.6

pygame 설치

>>> sudo pip3 install pygame

이제 한번 pygame 설치가 되나 봤더니

>>> sudo pip3 install pygame    
Requirement already satisfied: pygame in /usr/local/lib/python3.10/dist-packages (2.3.0)
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

여전히 그대로였다.. ㅜ
해석을 해보니 pygame이 이미 설치되어 있어서 이미 satisfied 되었다는 메시지가 표시되고 있는 것 같았다. 그러나 경고 메세지를 보면, root 사용자로 pip를 실행하면 시스템 패키지 관리자와 충돌하여 권한이 깨질 수 있으므로, 가상환경을 사용하는 것이 좋다고 한다. 따라서 가상환경이라는 것을 만들어서 해볼려고 한다.

2. 가상환경 만들기

여기서 가상환경 만들 때 venv를 사용할 것인데 venv는 파이썬에서 가상환경을 만들 때 사용하는 모듈 중 하나이다. 가상환경은 프로젝트마다 독립된 파이썬 환경을 생성하여 각 프로젝트에서 필요로 하는 모듈들을 별도로 설치하고 관리하는 것을 가능하게 한다.

가상환경을 사용하면, 다른 프로젝트에서 사용하는 패키지들과 충돌을 피하고, 프로젝트마다 필요한 패키지들을 설치하여 프로젝트마다 독립적인 환경을 구성할 수 있습니다. 또한, 프로젝트마다 필요한 파이썬 버전을 사용할 수도 있다.

venv 모듈은 파이썬 3.3 이상 버전부터 기본으로 포함되어 있으며, 가상환경 생성, 활성화, 비활성화, 삭제 등의 기능을 제공한다.

이제 본격적으로 가상환경을 만들어보자.

2-1. 가상환경을 위한 디렉토리 생성

>>> mkdir myenv
>>> cd myenv

참고로 가상환경 디렉토리명은 본인 원하는 이름으로 지어도 되지만 폴더 이름과 가상환경 이름을 일치시키는 것이 가장 직관적이고 편리할 것이다.

2-2. 파이썬 가상환경 생성

>>> python3 -m venv venv

여기서 오류가 떴다.

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv       
package using the following command.

    apt install python3.10-venv

You may need to use sudo with that command.  After installing the python3-venv   
package, recreate your virtual environment.

Failing command: ['/mnt/c/Users/유저명/OneDrive/문서/Coding/파일명1/파일명2/파일명3/myenv/venv/bin/python3', '-Im', 'ensurepip', '--upgrade', '--default-pip']

해당 에러는 venv를 사용하여 가상환경을 만들려고 시도했는데, 필요한 패키지가 설치되어있지 않아 발생한 것 같다.

에러 메시지에서 알려준대로, apt install python3.10-venv 명령어를 실행하여 필요한 패키지를 설치해주고 가상환경을 다시 만들어주자.

2-3. apt install python3.10-venv

>>> sudo apt update
>>> sudo apt install python3.10-venv
>>> python3.10 -m venv venv

python3.10 -m venv venv 명령어는 가상환경을 생성하는 명령어이며, 실행 시간은 컴퓨터의 성능에 따라 다를 수 있다. 일반적으로 몇 초 이내로 빠르게 생성되는데 가끔씩 오랜 시간이 걸리는 경우도 있다. 만약 명령어를 실행한 후 오래 기다려도 가상환경이 생성되지 않는다면, 다시 시도해보자. 나는 처음에 오래걸려서 Ctrl+C로 중단하고 다시 명령어 실행하니까 됬다.

 

이제 venv 폴더 안에 새로운 가상환경이 만들어졌을 것이다.

 

venv 폴더

 

2-4. 가상환경 활성화

>>> source venv/bin/activate

 

2-5. 가상환경에서 pygame 설치

>>> pip3 install pygame

이제 위와 같이 가상환경을 만들고 pygame을 설치하면, sudo 권한 없이도 pygame을 사용할 수 있다.

그런데 여기서 나는 또 오류가 발생했다 ㅡㅡ

Traceback (most recent call last):
  File "/mnt/c/Users/유저명/OneDrive/문서/Coding/폴더명1/폴더명2/폴더명3/폴더명4/파일명.py", line 1, in <module>
    import pygame
ModuleNotFoundError: No module named 'pygame'

이러한 문제는 가상환경에서 설치한 패키지가 시스템에 설치된 패키지와 충돌하거나 경로가 잘못 지정되어서 발생한 걸 수도 있다.

이런 경우에는 pip3 대신 python -m pip 명령어를 사용하여 가상환경에 패키지를 설치해보자. 가상환경을 먼저 활성화한 후 python -m pip install pygame 명령어를 사용한다.

>>> source venv/bin/activate
>>> python -m pip install pygame

 

이제 파이썬 실행하는 명령어인 python -u "/mnt/c/Users/유저명/OneDrive/문서/Coding/폴더명1/폴더명2/폴더명3/폴더명4/파일명.py" 를 해보니 실행이 된다!

 

>>> python -c "import pygame"
pygame 2.3.0 (SDL 2.24.2, Python 3.11.0)
Hello from the pygame community. https://www.pygame.org/contribute.html

 

python -c "import pygame" 해도 역시 잘 작동되는 걸 확인할 수 있다.😀😀

다 사용하고 나서 마지막에는 터미널에 가상환경을 비활성화해주는 deactivate를 치자. deactivate 명령어를 실행하지 않아도 가상환경에서 빠져나오는 것은 가능한데, 가상환경에서 빠져나오지 않은 채 다른 작업을 수행하면 가상환경에서 설치한 패키지와 충돌이 일어날 수 있으므로 추천하지 않는다. 따라서, 가상환경을 사용한 작업을 모두 마친 후에는 반드시 deactivate 명령어를 실행하여 가상환경에서 빠져나오는 것이 좋다.

 

 

참고로 source venv/bin/activate 명령어로 가상환경을 활성화하면 해당 폴더(myenv/venv)에서 실행되는 파이썬 파일에서는 가상환경에 설치한 모듈을 사용할 수 있다. 만약 다른 폴더에서도 해당 가상환경에 설치된 모듈을 사용하고 싶다면, 해당 폴더에서 source 명령어로 해당 가상환경을 활성화해해주면 된다. 그 가상환경을 activate 하는 것만으로도 해당 가상환경에서 패키지를 사용할 수 있다.

 

 

그러면 앞으로 새로운 프로젝트 폴더 만들어서 pygame 쓰고 싶다면 우리가 앞에서 했던 터미널 명령어 안쳐도 되고 source venv/bin/activate 이것만 하면 돼? 아니면 가상환경 폴더를 또 만들어야 해? 라고 생각할 수 있는데 가상환경은 프로젝트마다 따로 만들어주는 것이 좋다. 각각의 프로젝트마다 필요한 패키지들이 다르고, 패키지 버전이 충돌할 수 있기 때문에!

 

 

참고로 위 명령어들은 리눅스나 맥 운영체제에서 사용할 수 있는 명령어들이고, 윈도우에서는 명령어가 조금 다를 수 있다. 이 외에도 가상환경을 삭제하거나, 다른 가상환경을 만들기 위해 필요한 명령어들도 있으니 자세한건 아래 링크 참고하자.
https://docs.python.org/ko/3/tutorial/venv.html

12. Virtual Environments and Packages

 

 

후 pygame 하나 때문에 이렇게 진땀을 뺀 적은 처음이다 😵😵

 

 

요약 :

1. 가상환경 생성하기 => 터미널 창에 python3.10 -m venv venv

2. 가상환경 활성화하기 => 터미널 창에 source venv/bin/activate

3. pygame 설치하기 => pip3 install pygame

4. pygame이 정상적으로 실행되었는지 확인하기 => python -c "import pygame"

5. 가상환경 비활성화 하기 => deactivate

그러면 pygame 작동성공!