GNU Readline for Python

8.3.3 · active · verified Tue Apr 14

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.

Warnings

gotcha 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.
Fix: Check your existing `readline` implementation before installing. If it already provides GNU Readline or an adequate alternative, you might not need `gnureadline`.
gotcha 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.
Fix: Install `gnureadline` if you require full GNU Readline functionality on macOS. Use the `try: import gnureadline as readline` pattern in your code.
breaking 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`.
Fix: Uninstall the old `readline` package and install `gnureadline` instead (`pip install gnureadline`). Update import statements to `import gnureadline as readline`.
gotcha 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.
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`).
deprecated 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.
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.
gotcha 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.
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.

Install

pip install gnureadline Install via pip

Imports

readline
```
try:
    import gnureadline as readline
except ImportError:
    import readline
```
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.

Quickstart

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.

import atexit
import os

try:
    import gnureadline as readline
except ImportError:
    import readline

histfile = os.path.join(os.path.expanduser('~'), '.python_history')
try:
    readline.read_history_file(histfile)
    # Default history length is 500 lines. Adjust if needed.
    readline.set_history_length(1000)
except FileNotFoundError:
    pass

atexit.register(readline.write_history_file, histfile)

# Enable tab completion and other common bindings
readline.parse_and_bind('tab: complete')
readline.parse_and_bind('set editing-mode emacs') # or 'set editing-mode vi'

def completer(text, state):
    options = ['hello', 'world', 'apple', 'banana', 'orange', 'quit']
    matches = [s for s in options if s.startswith(text)]
    if state < len(matches):
        return matches[state]
    return None

readline.set_completer(completer)

print("Type 'quit' to exit. Use tab for completion.")
while True:
    try:
        line = input('Prompt> ')
        if line == 'quit':
            break
        print(f'You typed: {line}')
    except EOFError:
        break
    except KeyboardInterrupt:
        print(" (Press Ctrl-D or type 'quit' to exit)")

view raw JSON →