Install & Compatibility
Where this runs
tested against v0.15.1 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.437s · 27.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.402s · 28MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ReadlineEdit
✓ from urwid_readline import ReadlineEdit
This quickstart creates a simple Urwid application with a `ReadlineEdit` widget. It demonstrates basic input, modifying the widget's text on 'enter', and exiting the application by pressing 'q'. This provides a minimal but functional example of integrating `urwid-readline` into an Urwid application.
import urwid
from urwid_readline import ReadlineEdit
class MyReadlineEdit(ReadlineEdit):
def keypress(self, size, key):
if key == 'enter':
# When 'enter' is pressed, update the widget's text
self.set_edit_text(f'You typed: {self.edit_text}')
return None # Indicate that the key was handled
return super().keypress(size, key)
def exit_on_q(key):
if key in ('q', 'Q'):
raise urwid.ExitMainLoop()
# Create an instance of our custom ReadlineEdit
edit = MyReadlineEdit(edit_text='Hello, Urwid Readline!', multiline=True)
# Wrap the edit widget in a Filler to allow it to expand
fill = urwid.Filler(edit, 'top')
# Set up the main loop with our fill widget and a handler for unhandled input
loop = urwid.MainLoop(fill, unhandled_input=exit_on_q)
# Run the Urwid application
loop.run()
Debug
Known issues
breakingurwid-readline is built on top of the Urwid library. Breaking changes in Urwid (e.g., in versions 3.0.0 and 4.0.0) may affect urwid-readline applications. Always check the Urwid changelog when upgrading your Urwid dependency.fixRefer to the Urwid library's official documentation and changelog for specific migration steps. Ensure your Urwid dependency is compatible with your urwid-readline version and application code.
affects: Urwid 3.x, 4.x (and potentially earlier versions of Urwid)
gotchaWhen using `urwid-readline` with Python 3.14, older versions of the underlying `urwid` library might experience buffer overflow and unpacking errors related to terminal size detection. This was a known issue in `urwid`.fixUpgrade your `urwid` dependency to at least version 3.0.5 or newer to ensure compatibility and stability with Python 3.14+ environments.
affects: Urwid < 3.0.5 (specifically with Python 3.14)
gotchaDirect manipulation of Urwid widgets (e.g., for updating text or displaying alarms) can sometimes be non-intuitive and lead to unexpected behavior if not handled within the `urwid.MainLoop` context or by correctly managing widget states. This can be a source of frustration for new users.fixEnsure all UI updates are performed through the `urwid.MainLoop`'s event handling or `set_alarm` mechanism. For dynamic content, use `urwid.Text` or `urwid.Edit` widgets' `set_text` method appropriately. Consult the main Urwid documentation for best practices in updating display elements.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'urwid-readline'
Python import statements use underscores (_) for package names, not hyphens (-), even if the pip install name uses a hyphen.
fixUse an underscore in the import statement: `import urwid_readline` or `from urwid_readline import Readline`
ModuleNotFoundError: No module named 'urwid_readline'
The urwid-readline package has not been installed in the current Python environment.
fixInstall the package using pip: `pip install urwid-readline`
AttributeError: module 'urwid_readline' has no attribute 'readline'
The user attempted to import or use 'readline' (lowercase 'r') instead of the correct class name 'Readline' (uppercase 'R').
fixEnsure you are using the correct class name: `from urwid_readline import Readline` and then `Readline(...)`
TypeError: Readline.__init__() got an unexpected keyword argument 'text'
The Readline widget (which inherits from urwid.Edit) expects the initial text to be passed via the `edit_text` keyword argument, not `text`.
fixUse `edit_text` to provide the initial content for the Readline widget: `urwid_readline.Readline(edit_text='initial text')`
Upgrade
Version history
0.15.1latest on PyPI · released Sep 22, 2024
Audit
Dependencies
urwidrequiredCore dependency for the UI toolkit functionality.