Install & Compatibility
Where this runs
tested against v8.3.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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)")
Debug
Known issues
gotchaMany 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.fixCheck your existing `readline` implementation before installing. If it already provides GNU Readline or an adequate alternative, you might not need `gnureadline`.
affects: All versions
gotchaOn 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.fixInstall `gnureadline` if you require full GNU Readline functionality on macOS. Use the `try: import gnureadline as readline` pattern in your code.
affects: All versions, especially relevant for macOS users with Python 3.11+
breakingThe `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`.fixUninstall the old `readline` package and install `gnureadline` instead (`pip install gnureadline`). Update import statements to `import gnureadline as readline`.
affects: <= 6.2.4.2 of 'readline' package
gotchaBuilding `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.fixEnsure 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`).
affects: All versions
deprecatedOlder 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.fixAlways 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.
affects: All versions (installation method)
gotchaPython 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.fixBe 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.
affects: Python 3.13 and newer
Upgrade
Version history
8.3.3latest on PyPI · released Jan 6, 2026
Audit
Dependencies
ncursesrequiredRuntime dependency for the underlying GNU Readline library.
C compilerrequiredRequired for compiling the C-based extension module.
Python development headersrequiredRequired for building the Python extension.