{"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":"python","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,"search_vec":"'2026':87 '8.3.3':83 'achiev':40 'activ':61 'applic':13 'bundl':43 'cli':93 'code':51 'compat':68 'complet':92 'compliant':38 'consol':90 'current':80 'default':21 'editlin':30 'ensur':67 'frequent':64 'fulli':35 'gnu':1,8,36,48,76 'gnureadlin':5 'histori':91 'januari':86 'libedit':27 'librari':31,59,78 'like':17 'link':25,46 'linux':95 'maco':18,94 'maintain':62 'modul':23,57 'netbsd':28 'new':70 'often':24 'particular':14 'platform':16 'provid':6 'python':4,12,53,71 'readlin':2,9,22,37,49,56,77,88 'releas':84 'robust':7 'sourc':50 'standard':55 'static':45 'support':10 'termin':89 'under':75 'updat':65 'version':72,81","created_at":"2026-04-14T05:06:22.642824+00:00","updated_at":"2026-04-16T15:18:02.325056+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"8.3.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"http://github.com/ludwigschwardt/python-gnureadline","docs":null,"changelog":null,"pypi":"https://pypi.org/project/gnureadline/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-31","next_check":"2026-07-05","install_tag":null}}