{"id":5770,"library":"gnureadline","title":"GNU Readline for Python","description":"gnureadline provides robust GNU Readline support for Python applications, particularly on platforms like macOS where the default `readline` module often links against `libedit` (NetBSD's Editline library), which is not fully GNU Readline compliant. It achieves this by bundling and statically linking the GNU Readline source code with Python's standard `readline` module. The library is actively maintained, with frequent updates to ensure compatibility with new Python versions and the underlying GNU Readline library; the current version is 8.3.3, released in January 2026.","status":"active","version":"8.3.3","language":"en","source_language":"en","source_url":"http://github.com/ludwigschwardt/python-gnureadline","tags":["readline","terminal","console","history","completion","cli","macos","linux"],"install":[{"cmd":"pip install gnureadline","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Runtime dependency for the underlying GNU Readline library.","package":"ncurses","optional":false},{"reason":"Required for compiling the C-based extension module.","package":"C compiler","optional":false},{"reason":"Required for building the Python extension.","package":"Python development headers","optional":false}],"imports":[{"note":"This pattern allows code to prioritize `gnureadline` if available, falling back to the standard library's `readline` module if not. The module is named `gnureadline` to avoid a direct name clash with the standard library's `readline` module.","symbol":"readline","correct":"try:\n    import gnureadline as readline\nexcept ImportError:\n    import readline"}],"quickstart":{"code":"import atexit\nimport os\n\ntry:\n    import gnureadline as readline\nexcept ImportError:\n    import readline\n\nhistfile = os.path.join(os.path.expanduser('~'), '.python_history')\ntry:\n    readline.read_history_file(histfile)\n    # Default history length is 500 lines. Adjust if needed.\n    readline.set_history_length(1000)\nexcept FileNotFoundError:\n    pass\n\natexit.register(readline.write_history_file, histfile)\n\n# Enable tab completion and other common bindings\nreadline.parse_and_bind('tab: complete')\nreadline.parse_and_bind('set editing-mode emacs') # or 'set editing-mode vi'\n\ndef completer(text, state):\n    options = ['hello', 'world', 'apple', 'banana', 'orange', 'quit']\n    matches = [s for s in options if s.startswith(text)]\n    if state < len(matches):\n        return matches[state]\n    return None\n\nreadline.set_completer(completer)\n\nprint(\"Type 'quit' to exit. Use tab for completion.\")\nwhile True:\n    try:\n        line = input('Prompt> ')\n        if line == 'quit':\n            break\n        print(f'You typed: {line}')\n    except EOFError:\n        break\n    except KeyboardInterrupt:\n        print(\" (Press Ctrl-D or type 'quit' to exit)\")\n","lang":"python","description":"This quickstart demonstrates how to import and initialize `gnureadline` to provide enhanced command-line editing, history persistence, and tab completion for an interactive Python prompt. It shows how to use a `try-except` block to gracefully handle environments where `gnureadline` might not be installed, set up history file management, and register a custom completer function."},"warnings":[{"fix":"Check your existing `readline` implementation before installing. If it already provides GNU Readline or an adequate alternative, you might not need `gnureadline`.","message":"Many modern Python distributions (e.g., standard Linux, Anaconda, IPython 5.0+) already include proper GNU Readline or use a capable alternative like `prompt_toolkit`. Installing `gnureadline` might be unnecessary or lead to conflicts. Verify if you truly need it by running `python -c \"import readline; print(readline.__doc__)\"` and checking if the output indicates `libedit` (where `gnureadline` would be beneficial) or GNU readline.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `gnureadline` if you require full GNU Readline functionality on macOS. Use the `try: import gnureadline as readline` pattern in your code.","message":"On macOS, the system Python and Homebrew-installed Python versions 3.11 and newer often default to `libedit` (NetBSD's Editline library) for the `readline` module, which offers a different feature set than GNU Readline. `gnureadline` is specifically designed to provide the full GNU Readline experience in such environments.","severity":"gotcha","affected_versions":"All versions, especially relevant for macOS users with Python 3.11+"},{"fix":"Uninstall the old `readline` package and install `gnureadline` instead (`pip install gnureadline`). Update import statements to `import gnureadline as readline`.","message":"The `readline` PyPI package was deprecated and renamed to `gnureadline` to avoid a name clash with the standard library's `readline` module. Users of the old `readline` package must migrate to `gnureadline`.","severity":"breaking","affected_versions":"<= 6.2.4.2 of 'readline' package"},{"fix":"Ensure you have the necessary development tools and libraries installed. For Debian/Ubuntu: `sudo apt-get install libncurses5-dev build-essential python3-dev` (adjust python-dev package for your Python version). For macOS, ensure Xcode Command Line Tools are installed (`xcode-select --install`).","message":"Building `gnureadline` requires system-level dependencies such as the `ncurses` development library and a C compiler with Python development headers. Installation via `pip` may fail if these are not pre-installed on your system.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `pip install gnureadline`. For enabling `gnureadline` in the standard interactive Python shell, refer to the `override_readline` script (available from the GitHub repository) or configure your `~/.pythonrc` with appropriate imports and bindings.","message":"Older documentation and discussions might suggest using `easy_install` for `gnureadline` as a 'drop-in replacement' in the standard Python shell. `easy_install` is deprecated and should no longer be used.","severity":"deprecated","affected_versions":"All versions (installation method)"},{"fix":"Be aware of potential behavioral changes in the interactive shell with Python 3.13+. While `gnureadline` still provides core functionality, some features might be handled by Python's native implementation.","message":"Python 3.13 introduced a new interactive interpreter which reimplements some GNU Readline functionality internally, potentially bypassing `gnureadline` for certain features (e.g., Ctrl-R history search). This can lead to subtle differences in behavior.","severity":"gotcha","affected_versions":"Python 3.13 and newer"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}