{"id":8786,"library":"wxpython","title":"wxPython","description":"wxPython is a cross-platform GUI toolkit for Python, providing a native look and feel on Windows, macOS, and Linux by wrapping the wxWidgets C++ library. The current version (4.x, \"Phoenix\") is a re-implementation focused on improved speed, maintainability, and extensibility. It is actively maintained with regular releases.","status":"active","version":"4.2.5","language":"en","source_language":"en","source_url":"https://github.com/wxWidgets/Phoenix","tags":["GUI","desktop","cross-platform"],"install":[{"cmd":"pip install wxPython","lang":"bash","label":"Install latest stable version"}],"dependencies":[],"imports":[{"symbol":"wx","correct":"import wx"}],"quickstart":{"code":"import wx\n\nclass MyFrame(wx.Frame):\n    def __init__(self, parent, title):\n        super(MyFrame, self).__init__(parent, title=title, size=(300, 200))\n        panel = wx.Panel(self)\n        text = wx.StaticText(panel, label=\"Hello, wxPython!\", pos=(80, 50))\n        button = wx.Button(panel, label=\"Click Me\", pos=(80, 100))\n        button.Bind(wx.EVT_BUTTON, self.on_click)\n        self.Show()\n\n    def on_click(self, event):\n        wx.MessageBox(\"Button clicked!\", \"Info\", wx.OK | wx.ICON_INFORMATION)\n\nif __name__ == '__main__':\n    app = wx.App(False) # False to not redirect stdout/stderr\n    frame = MyFrame(None, \"Simple wxPython App\")\n    app.MainLoop()","lang":"python","description":"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."},"warnings":[{"fix":"Consult the \"Phoenix Migration Guide\" in the official documentation to adapt existing code.","message":"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.","severity":"breaking","affected_versions":"<4.0 to 4.x"},{"fix":"Use `wx.CallAfter()`, `wx.CallLater()`, or `wx.PostEvent()` to safely marshal updates from worker threads to the GUI thread.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Performing long-running computations directly within an event handler on the main GUI thread will block the `MainLoop()`, making the application unresponsive (\"frozen\").","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `import pubsub` directly and adapt import paths (e.g., change `from wx.lib.pubsub import pubsub` to `import pubsub`).","message":"In wxPython 4.x, the `wx.lib.pubsub` module is deprecated.","severity":"deprecated","affected_versions":"4.0+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Rename your Python script to something other than `wx.py` (e.g., `my_app.py`) to avoid conflicts with the actual `wxPython` module.","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.","error":"ImportError: No module named 'wx'"},{"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.","cause":"Attempting to modify GUI components directly from a secondary thread, or a long-running task blocking the main event loop.","error":"Application crashes unexpectedly or freezes solid."},{"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.","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).","error":"Command '...' failed with exit code 1' during `pip install wxPython`."},{"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.","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.","error":"Exceptions or errors occur but disappear, or only show a brief console message."}]}