Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 41 ยท Getting Started

Installing Pygame

Install pygame-ce or pygame with pip on Windows, macOS and Linux, use a virtual environment, verify the install with a short script and fix the common errors.

Installing Pygame takes one command, but a few details save you hours later: which Python you use, whether you work in a virtual environment, and not mixing pygame with pygame-ce. This lesson walks through all of it on Windows, macOS and Linux, then shows how to confirm that the install works.

Before you start: check Python

Pygame needs a reasonably recent Python 3. Open a terminal (Command Prompt or PowerShell on Windows, Terminal on macOS and Linux) and run:

Terminal
python --version

On macOS and Linux the command is often python3. If you see something like Python 3.12.4, you are ready. If the command is not found, install Python from python.org (on Windows tick Add python.exe to PATH in the installer) or through your system's package manager.

Create a virtual environment

A virtual environment is a private folder of packages for one project. It keeps Pygame from clashing with other things on your computer and makes uninstalling trivial (delete the folder).

Terminal
# Windows
python -m venv .venv
.venv\Scripts\activate

# macOS and Linux
python3 -m venv .venv
source .venv/bin/activate

After activation your prompt starts with (.venv). Everything you install with pip now goes into that environment. Remember to activate it each time you open a new terminal for the project.

Terminal
python -m pip install --upgrade pip
python -m pip install pygame-ce

Using python -m pip guarantees that pip belongs to the Python you are actually running. If you prefer the original package, install pygame instead:

Terminal
python -m pip install pygame

Warning: Do not install both. They provide the same pygame module name, and having both leads to confusing errors. If you installed the wrong one, run python -m pip uninstall pygame pygame-ce and then install just one.

Platform notes

  • Windows: wheels (prebuilt packages) exist for current Python versions, so pip just works. Use py -m pip install pygame-ce if python is not on the PATH.
  • macOS: pip works on Intel and Apple Silicon. If you use Homebrew Python, always use a virtual environment, because system-wide pip installs are blocked.
  • Linux: pip wheels work on most distributions. On Raspberry Pi OS or when a wheel is unavailable, install the system package (for example sudo apt install python3-pygame) or the SDL development libraries and let pip compile it.
  • Editors: in VS Code, PyCharm and similar editors, select the interpreter from .venv so the editor sees the library.

Verify the install

Run this tiny script on your computer. A successful install prints a version line and the version numbers:

Python
import pygame

print("Pygame version:", pygame.version.ver)
print("SDL version:", pygame.get_sdl_version())
print("Is Community Edition:", hasattr(pygame, "IS_CE"))

When you import Pygame normally it also prints a banner such as pygame-ce 2.5.x (SDL 2.x.x, Python 3.x.x) and a link to the website. Set the environment variable PYGAME_HIDE_SUPPORT_PROMPT=1 before importing if you want to hide it, as the examples on this site do.

Try it: a version-check script

The runner on this site has pygame-ce built in, so you can run the same diagnostic here. It also shows how to compare versions the safe way, as tuples of numbers rather than strings.

Python Check the Pygame version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last two lines are a classic trap: compare version numbers as tuples of integers, never as strings.

Try it: a module checklist

If something fails later, the quickest diagnosis is to ask which Pygame parts are available. This script imports each module and reports ok or missing. A missing module on your computer usually means a broken SDL install. Here, display and mixer are expected to report problems when used because the browser runner has no screen or speakers.

Python Which modules import?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common problems

Symptom Likely cause and fix
ModuleNotFoundError: No module named 'pygame' Installed in a different Python. Activate your .venv or run python -m pip install pygame-ce with the same python you use to run the script.
pip is not recognized Use python -m pip ... instead.
Build errors while installing Your Python is too new or too old for a prebuilt wheel. Use a supported Python version, or upgrade pip.
AttributeError: module 'pygame' has no attribute ... A file of yours named pygame.py shadows the library. Rename it.
Weird behavior after switching packages Both packages are installed. Uninstall both, install one.
pygame.error: No available video device You are on a server without a display. Set SDL_VIDEODRIVER=dummy to test without a window.

Tip: Never name your own file pygame.py, random.py or time.py. Python imports your file instead of the library.

Keeping dependencies tidy

Record what your project needs in a requirements.txt file with one line, pygame-ce, or let pip write it with python -m pip freeze > requirements.txt. Then a friend (or you, on a new computer) can recreate the environment with python -m pip install -r requirements.txt. We return to this when you package your game.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you run pip as python -m pip install ...?

    A computer can have several Pythons. python -m pip ties the install to the interpreter you are actually using.
  2. 2. What happens if you install both pygame and pygame-ce in one environment?

    Both provide the module pygame, so files overwrite each other and produce confusing errors. Keep one.
  3. 3. Your script is called pygame.py and import pygame fails with strange errors. Why?

    The current folder is searched first, so your file shadows the real library. Rename it.
  4. 4. How should you compare version numbers in code?

    As strings, "2.10" < "2.9" is true. Tuples of integers compare correctly.

Summary

  • Use a virtual environment and python -m pip install pygame-ce.
  • Install either pygame or pygame-ce, never both.
  • Verify with pygame.version.ver and pygame.get_sdl_version().
  • Never name your own file pygame.py.
  • Compare versions as integer tuples.

Next: Import and Initialize