How to Solve "ModuleNotFoundError: No module named 'pygame'" in Python
The error ModuleNotFoundError: No module named 'pygame'
means Python can't find the pygame
library, which is used for game development. This usually happens because pygame
isn't installed, is installed in the wrong environment, or your IDE/Jupyter isn't set up right.
This guide provides a complete walkthrough for installing pygame
and fixing common problems.
Installing pygame
(The Basic Solution)
The standard way to install pygame
is using pip
:
pip install pygame
-
Multiple Python Versions: If you have multiple Python versions, use
pip3
(orpip3.9
, etc.):pip3 install pygame
-
Permissions Errors: If you get a permissions error:
sudo pip3 install pygame # Linux/macOS (use with CAUTION!)
pip install pygame --user # Install for the current user onlyUsing virtual environments (explained below) is the best way to avoid permissions issues.
-
python -m pip
: Ifpip
isn't in yourPATH
:python -m pip install pygame # Or python3 -m pip, py -m pip
-
Anaconda: if you are using Anaconda, install
pygame
using:conda install -c anaconda pygame
Verifying the Installation
After installing, verify that pygame
is accessible with a simple script:
import pygame
print(pygame.__version__) # Print the pygame version
# Example: start the aliens demo
# This also tests that everything is working.
pygame.examples.aliens.main()
- If this code runs without errors and opens the example, then the installation was successful.
If you get a ModuleNotFoundError
, proceed to troubleshooting.
Troubleshooting ModuleNotFoundError
Virtual Environments (Essential)
Always use virtual environments:
-
Create:
python3 -m venv venv
(orpython -m venv venv
, orpy -m venv venv
) -
Activate:
- Linux/macOS:
source venv/bin/activate
- Windows (cmd):
venv\Scripts\activate.bat
- Windows (PowerShell):
venv\Scripts\Activate.ps1
- If you get PowerShell errors, use this to enable script execution:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
- If you get PowerShell errors, use this to enable script execution:
- Linux/macOS:
-
Install:
pip install pygame
(inside the activated environment).
Your terminal prompt will change (e.g., (venv) $
).
Multiple Python Versions:
- Check:
python --version
(orpython3 --version
) - Correct
pip
: Use thepip
(pip3
,python -m pip
) that corresponds to your intended Python version.
IDE Configuration (VS Code, PyCharm)
Configure your IDE to use the correct interpreter/environment.
Jupyter Notebook
Install within a notebook cell:
!pip install pygame
Ensure your Jupyter kernel uses the right environment.
Naming Conflicts
Never name your files pygame.py
.
Reinstalling pygame
pip uninstall pygame
pip install pygame
Installation Instructions for Specific Environments
Windows
- CMD or Powershell
- Use
pip install pygame
, orpy -m pip install pygame
macOS / Linux
- Open terminal.
pip3 install pygame
Ubuntu/Debian/Mint
You might also install pygame using apt:
sudo apt-get install python3-pygame
CentOS/Fedora/Red Hat
sudo yum install python3-pygame
OpenSUSE:
sudo zypper install python3-pygame
Arch/Manjaro
sudo pamac install python-pygame
Anaconda
conda install -c anaconda pygame
Jupyter Notebook (within a cell):
!pip install pygame
Handling "Import 'pygame' could not be resolved" (Pylance - VS Code)
- Select the correct Python interpreter, or restart VS Code.
- Add the comment
# type: ignore
to the import statement to disable the warning.
import pygame # type: ignore
Conclusion
The ModuleNotFoundError: No module named 'pygame'
error almost always indicates an installation or environment issue.
- Always use virtual environments.
- Install with the correct
pip
command. - Ensure your IDE/Jupyter setup is correct.
This guide provides comprehensive steps for installation, verification, and troubleshooting, enabling you to start creating games with Pygame.