Skip to main content

GUIs with pygame — wiki

From time to time, questions about GUI elements for pygame come up. The following sections give some links to GUI modules and libraries written for pygame and try - where possible - to give advice to which library you should refer for your pygame project.

A quick note to those who developed their own GUI system for Pygame: You are encouraged to add it to this page. Simply add a description, preferably in the form that the already existing ones provide, at the bottom of this page.

Which GUI type are you

Before you just use the first GUI library you find on the internet, you should ask yourself these questions:

  • How much GUI do I need?
  • How special are my requirements on GUI elements?
  • What type of project am I working on?

Although the last question might sound a bit like an insult, it is possibly the most important question for your GUI decision. People (especially newcomers to game programming) tend to forget about their goal and, which is quite more important, the impression the project will have on its users.

Arcade games such as a Space Invaders project mostly do not need many GUI elements. It may need a text entry for the highscores and maybe some button basics for the main game menu. In contrast, a full featured economy simulation game like the good old Oil Imperium would need text entry boxes, buttons, lists for statistical data, table-like elements, spinner buttons for money amounts and many, many more.

Summing up those both fictional cases, the first one would need around two GUI elements while the second would need more than five. Additionally, if the arcade game has ingame GUI elements, those need to have a low reaction latency, while the economy simulation is mostly in the same gaming state showing an only slowly changing game window.

The user perspective

Another issue you have to deal with is the user perspective. The user perspective is a kind of usability from the user point of view and - in this case - simply means: "How much effort do I need to invest to run this game?". Far too often this question is silently ignored by newcomers, thus it is brought up here. If a user first has to install dependency X for the GUI you have integrated, then has to get and install the GUI and then can run the game, it is possibly too late (unless your game has outstanding concept/graphics/gameplay). They simply will remove it from their computer.

You therefore should check if the GUI library you are about to integrate in your game can be incorporated in your game distribution or if it has many third party dependencies, for which the integration/installation effort is higher than the benefit.

First of all, pygame relies on the SDL, which means that it can only have one window at a time. Thus, trying to implement multiple Gtk, Qt, ... application instances that use pygame, is an impossibility. The second problematic reason is that those toolkits use their own main loop, which possibly forces you to pipe their events to your pygame instance and vice versa. And to mention some other points in short: Drawing the toolkit elements on the pygame window is impossible and the SDL/pygame fullscreen mode will be problematic.

As you see, using those toolkits together with pygame will, in nearly any case, cause more problems than their usage solves. So let's quickly go to the next section.

GUI libraries

Now that you clarified those questions, you should know enough about the requirements you have on the specific GUI library type you want. The following presents a (not always up to date and possibly always incomplete) list of GUI libraries and modules suitable for the use with pygame. The entries also mention the basic capabilities and constraints the particular library has.

There is also a GUI comparision (2005) available, which was made by David Keeney for his own pygame project.

ThorPy is a GUI library for pygame that is pip install-able with excellent documentation.

Easy to incorporate all-purpose library with own GUI module. Includes the usual GUI element functionality with some nice additions. Due to its relatively low internal complexity, the library is suitable for a low to medium amount of GUI elements and is easy to integrate into existing game code. The GUI elements have a relatively low response time and low overhead, which makes it very suitable for arcade games or games with a real-time approach.

A new release compatible with Python 3 is available as "pygame-pgu" pip install

  • rich GUI element set
  • includes image based theme engine
  • very pygame oriented. The paint() methods take pygame.Surfaces, the event() methods take pygame.Events.pgu is easy to extend with your own pygame based widgets.
  • additional game functionalities besides GUI
  • easy to incorporate into a game
  • library is about to reach a mature, stable state
  • very suitable for arcade or rt games
  • very easy-to-use API, so it is quite nice for the rapid development of small applications (several custom level editors have been created using pgu)
  • depends on python and pygame only
pgu in a level editor application

pgu in a game level selection interface
OcempGUI (unmaintained)

OcempGUI example applicationSpecialized GUI library with a rich GUI element set and a high functionality. It serves nearly all needs expected from a GUI library, which includes a relatively high (internal) complexity. Very suitable for a medium to high and very high GUI amount, a low GUI amount should be realized with another library, because OcempGUI would be overkill here. The incorporation into own distributions is possible, but more complex than with pgu, yet easy to integrate into existing code. As of version 0.1.1, includes internal support for Twisted, making it suitable for network games as well. Due to its high internal complexity the GUI element response time is somewhat lower than with other libraries, so that it should not be used in arcade like games or games, that have a real-time approach, criar sites.

Because of its rich feature set, it serves most needs of round based game types, simulation games, network games, or non-game applications.

OcempGUI component diagram
  • rich GUI element set based on pygame.
  • high abstraction layers, own GUI elements can be created with less effort
  • various accessibility (a11y) support layers reaching from full keyboard navigation support a system integration via the ATK/AT-SPI standards
  • library supports own drawing engines and themes for user-defined look-and-feel
  • includes internal support for Twisted via the TwistedRenderer
  • easy to incorporate
  • library is currently in a beta state, but very stable
  • very suitable for round based and simulation games or applications
  • full z-axis support using layers
  • minimum dependencies are python and pygame only

General GUI open-source-library under development. It serves the most basic GUI-widgets (Label, Entry, Button, Border) and plans to extend to more areas (e.g. its own currently experimental 2D-light-engine). API-wise the library uses a object-orientated approach: Especially regarding widgets, using PyGame's Sprite-class; A Widget's properties are set through its constructor or calling methods on existing instances. Currently suitable for a low/medium GUI amount (e.g. arcade-like games, start menues). More complex GUI's should be realized with another library, since PyGVisuals is currently lacking a layout-manager.

  • currently under active development
  • high abstraction widget-classes based on Pygame-Sprites, custom widget's can be easily added
  • experimental, game-extending features (e.g. 2D-light/shadow-engine)
  • library is currently in an alpha stage, but it will get more stable over time
  • open-sourced: anybody can contribute to PyGVisuals, making it more stable and adding to its features
  • BSD-license: contens of this library can be used to one's liking as long as one follows the licence's terms and conditions
  • minimum dependencies are python and pygame only