Skip to main content

How to Resolve "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 (or pip3.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 only

    Using virtual environments (explained below) is the best way to avoid permissions issues.

  • python -m pip: If pip isn't in your PATH:

    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:

  1. Create: python3 -m venv venv (or python -m venv venv, or py -m venv venv)

  2. 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

  3. Install: pip install pygame (inside the activated environment).

Your terminal prompt will change (e.g., (venv) $).

Multiple Python Versions:​

  • Check: python --version (or python3 --version)
  • Correct pip: Use the pip (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
note

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, or py -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.

Table of Contents