wxPython

Common errors

• ImportError: No module named 'wx'

  cause A common mistake is naming a user's Python script `wx.py`. When Python tries to `import wx`, it finds the user's script first, which doesn't contain the expected `wx` module, leading to this error.
  fix Rename your Python script to something other than `wx.py` (e.g., `my_app.py`) to avoid conflicts with the actual `wxPython` module.

• Application crashes unexpectedly or freezes solid.

  cause Attempting to modify GUI components directly from a secondary thread, or a long-running task blocking the main event loop.
  fix Ensure all GUI updates are dispatched to the main thread using `wx.CallAfter()` or `wx.PostEvent()`. For long computations, run them in a separate thread and use `wx.CallAfter()` for result updates.

• Command '...' failed with exit code 1' during `pip install wxPython`.

  cause wxPython often compiles the underlying wxWidgets C++ library from source if a pre-built wheel is not available for your specific Python version, OS, and architecture. This compilation can fail due to missing build tools (e.g., C++ compiler, development headers) or specific platform issues (e.g., on ARM Macs for older wxPython versions).
  fix Ensure you have the necessary C++ build tools installed for your system (e.g., `build-essential` on Linux, Xcode command-line tools on macOS, Visual Studio build tools on Windows). For macOS M1/M2, ensure you have an up-to-date Python and wxPython version that provides compatible wheels or proper build support.

• Exceptions or errors occur but disappear, or only show a brief console message.

  cause By default, `wx.App` might redirect `stdout`/`stderr` or handle exceptions in a way that makes them hard to see, especially in graphical environments.
  fix Initialize `wx.App(redirect=False)` to prevent redirection. For better error visibility, wrap `app.MainLoop()` in a `try...except` block and display exceptions using `wx.MessageBox` or log them.

Warnings

• breaking Code written for older "Classic" wxPython (pre-4.0) is not fully compatible with wxPython 4.x (Phoenix) due to significant internal re-implementation and API cleanups. Many `wx.lib` modules changed or were removed, and string handling became exclusively Unicode.
  Fix: Consult the "Phoenix Migration Guide" in the official documentation to adapt existing code.
• gotcha Directly manipulating GUI elements or making wxPython calls from a worker/background thread can lead to application crashes, freezes, or unpredictable behavior. All GUI-related operations must occur on the main thread.
  Fix: Use `wx.CallAfter()`, `wx.CallLater()`, or `wx.PostEvent()` to safely marshal updates from worker threads to the GUI thread.
• gotcha Performing long-running computations directly within an event handler on the main GUI thread will block the `MainLoop()`, making the application unresponsive ("frozen").
  Fix: Offload time-consuming tasks to separate threads or processes. Use thread-safe methods (`wx.CallAfter`, `wx.PostEvent`) to communicate results back to the GUI thread. Consider `wxasync` for `asyncio` integration for cooperative multitasking.
• deprecated In wxPython 4.x, the `wx.lib.pubsub` module is deprecated.
  Fix: Use `import pubsub` directly and adapt import paths (e.g., change `from wx.lib.pubsub import pubsub` to `import pubsub`).

Install

• pip install wxPython Install latest stable version

Imports

• wx

  import wx

Quickstart

This quickstart creates a basic wxPython application with a main window, a static text label, and a button. Clicking the button displays a message box. The `wx.App(False)` initialization prevents stdout/stderr redirection, and `app.MainLoop()` starts the event processing.

import wx

class MyFrame(wx.Frame):
    def __init__(self, parent, title):
        super(MyFrame, self).__init__(parent, title=title, size=(300, 200))
        panel = wx.Panel(self)
        text = wx.StaticText(panel, label="Hello, wxPython!", pos=(80, 50))
        button = wx.Button(panel, label="Click Me", pos=(80, 100))
        button.Bind(wx.EVT_BUTTON, self.on_click)
        self.Show()

    def on_click(self, event):
        wx.MessageBox("Button clicked!", "Info", wx.OK | wx.ICON_INFORMATION)

if __name__ == '__main__':
    app = wx.App(False) # False to not redirect stdout/stderr
    frame = MyFrame(None, "Simple wxPython App")
    app.MainLoop()