xtekky/gpt4free · error · ImportError

pystray is required for system tray support. Install it with

Error message

pystray is required for system tray support. Install it with: pip install pystray pillow

What it means

g4f/tray.py raises this ImportError when the system-tray entry point tries to 'import pystray' and it is not installed. pystray is an optional dependency used to show the g4f tray icon and server controls, so it is not bundled with the base install.

Source

Thrown at g4f/tray.py:118

):
    """
    Launch the g4f system tray application.

    Parameters
    ----------
    port : int
        Port for the API server (default 1337).
    host : str
        Bind host for the API server (default 0.0.0.0).
    debug : bool
        Enable verbose logging.
    no_autostart : bool
        If True, the API server is NOT started automatically on launch.
    """
    try:
        import pystray
    except ImportError:
        raise ImportError(
            "pystray is required for system tray support. "
            "Install it with: pip install pystray pillow"
        )

    from g4f.api import AppConfig, run_api

    browser_url = f"http://127.0.0.1:{port}"

    # ------------------------------------------------------------------ #
    # Server management                                                    #
    # ------------------------------------------------------------------ #
    _server_thread: Optional[threading.Thread] = None
    _server_running = threading.Event()

    def _start_server():
        nonlocal _server_thread
        if _server_running.is_set():
            return

View on GitHub (pinned to 973504e177)

Solutions

Install the missing dependency: pip install pystray pillow
If you do not need the tray icon, use the non-tray entry point (e.g. run the API directly via g4f.api) instead of g4f/tray.py
Add pystray and pillow to your project's requirements to keep the install reproducible

Example fix

# before
python -m g4f.tray  # ImportError: pystray is required

# after
pip install pystray pillow
python -m g4f.tray

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util

has_pystray = importlib.util.find_spec("pystray") is not None

Try / catch

try:
    from g4f.tray import run  # or the tray entry point
except ImportError as e:
    if "pystray" in str(e):
        # degrade: start the API server without the tray icon
        from g4f.api import run_api
    else:
        raise

Prevention

Install optional GUI extras up front: pip install pystray pillow
Declare pystray/pillow in requirements when the tray is used
On headless servers, use the API entry point instead of the tray

When it happens

Trigger: Invoking the tray launcher (g4f/tray.py's run function, e.g. via the GUI/tray entry point) in an environment where 'pip install pystray' was never run or pystray was uninstalled.

Common situations: Installing g4f without the GUI/tray extras; a venv created from a requirements list that omits pystray; running on a headless server where pystray was skipped intentionally.

Related errors

AI-assisted analysis of xtekky/gpt4free@973504e177 (2026-08-14). Data as JSON: /api/errors/7b3e4a2a88c3ebc7. Report an issue: GitHub.