urwid/urwid: Console user interface library for Python (official repo)

Urwid ===== |pypi| |docs| |gitter| |ci| |pre-commit| |coveralls|

About =====

Urwid is a console user interface library for Python on Linux, OSX, Cygwin or other unix-like OS and partially supports Windows OS (see below).

It includes many features useful for text console application developers including:

• Applications resize quickly and smoothly
• Automatic, programmable text alignment and wrapping
• Simple markup for setting text attributes within blocks of text
• Powerful list box with programmable content for scrolling all widget types
• Your choice of event loops: Twisted, Glib (deprecated), Tornado, asyncio, trio, ZeroMQ or select-based loop
• Pre-built widgets include edit boxes, buttons, check boxes and radio buttons
• Display modules include raw, curses, and experimental LCD and web displays
• Support for UTF-8, simple 8-bit and CJK encodings
• 24-bit (true color), 256 color, and 88 color mode support
• Compatible with Python 3.11+ and PyPy

Installation ============

To install using pip

.. code:: bash

pip install urwid

For advanced functionality extra requirements need to be installed. Example for ZeroMQ event loop and LCD display:

.. code:: bash

pip install urwid[serial,zmq]

Alternatively if you are on Debian or Ubuntu

.. code:: bash

apt-get install python3-urwid

Windows support notes =====================

Windows support is limited to the Windows 10+ due to ANSI support requirement.

• Not supported:

1. Terminal widget and all related render API (TermCanvas, TermCharset, TermModes, TermScroller)
2. Any file descriptors except sockets (Windows OS limitation)
3. ZMQEventLoop.

• Special requirements:

1. Extra libraries required for curses display support:

pip install urwid[curses]

• CursesDisplay incorrectly handles mouse input in case of fast actions.
• Only UTF-8 mode is supported.

Testing =======

To run tests locally, install & run tox. You must have appropriate Python versions installed to run tox for each of them.

To test code in all Python versions:

.. code:: bash

tox # Test all versions specified in tox.ini tox -e py311 # Test Python 3.11 only tox -e py313t # Test Python 3.13 with free-threading tox -e pypy311 # Test PyPy 3.11 tox -e py311,py312,pypy311 # Test specific versions

Testing different Python implementations ----------------------------------------

CPython standard (default)

Tests all optional extras including C extensions (glib, zmq, twisted).

.. code:: bash

tox -e py313

Free-threaded CPython (3.13+)

Tests with compatible extras (tornado, trio, twisted, serial). Excludes C extensions without free-threading wheel support.

.. code:: bash

tox -e py313t # Python 3.13 free-threaded (PEP 703) tox -e py314t # Python 3.14 free-threaded tox -e py315t # Python 3.15 free-threaded

PyPy

Tests with compatible extras (tornado, trio, serial). Excludes problematic C extensions.

.. code:: bash

tox -e pypy311 # PyPy 3.11 tox -e pypy312 # PyPy 3.12

GraalPy

Tests with compatible extras (tornado, serial). Excludes extras that need C extensions GraalPy doesn't support (glib, zmq) or that have known compatibility issues (trio, twisted). GraalPy also ships no `_curses module, so curses-dependent tests are expected to fail, and the Terminal widget (urwid.vterm) is unsupported since its fcntl/pty usage doesn't work on GraalPy, so its tests are skipped rather than run.

• CPython 3.11, 3.12, 3.13, 3.14, 3.15
• CPython 3.13+ with free-threading (PEP 703 --disable-gil)
• PyPy 3.11
• GraalPy 3.12, 3.13 (experimental)

Full support for all optional features. All extras (curses, glib, serial, tornado, trio, twisted, zmq) can be installed. On Windows, the curses extra cannot be installed on Python 3.15 yet: windows-curses publishes no 3.15 wheel.

• ✅ Supported: core, tornado, trio, serial, lcd
• ⚠️ Limited: twisted (may have issues, test before using)
• ❌ Unsupported: glib, zmq (C extensions with limited PyPy support)
• ❌ Unsupported: curses on Windows (PyPy for Windows ships no _curses module and windows-curses publishes

Urwid core and the select/asyncio event loops are supported. Some extras, display modules, and the Terminal widget are not:

• ✅ Supported: core, tornado, serial, lcd
• ❌ Unsupported: curses (GraalPy ships no _curses module), glib, zmq, twisted, trio (no C

• ❌ Unsupported: GraalPy 3.11 (GraalPy 24), whose os module has no O_NOFOLLOW and whose ASCII and Latin-1

wardi _

and3rson _, tonycpsu _, ulidtko _, penguinolog _

1in7billion _, abadger _, agrenott _, akorb _, alethiophile _, aleufroy _, alobbs _, amjltc295 _, and-semakin _, andrewshadura _, andy-z _, anttin2020 _, Apteryks _, Arfrever _, AutoAwesome _, belak _, berney _, bk2204 _, BkPHcgQL3V _, bwesterb _, carlos-jenkins _, Certseeds _, Chipsterjulien _, chrisspen _, cltrudeau _, Codeberg-AsGithubAlternative-buhtz _, cortesi _, d0c-s4vage _, derdon _, dholth _, dimays _, dlo _, dnaeon _, doddo _, douglas-larocca _, drestebon _, dsotr _, dwf _, EdwardBetts _, elenril _, EnricoBilla _, extempore _, fabiand _, floppym _, flowblok _, fmoreau _, goncalopp _, Gordin _, GregIngelmo _, grzaks _, gurupras _, HarveyHunt _, Hoolean _, hukka _, hydratim _, ids1024 _, imrek _, isovector _, itaisod _, ixxra _, jeblair _, johndeaton _, jonblack _, jspricke _, kedder _, Kelketek _, KennethNielsen _, kesipyc _, kkrolczyk _, Kwpolska _, Lahorde _, laike9m _, larsks _, lfam _, lgbaldoni _, lighth7015 _, livibetter _, Lothiraldan _, Mad-ness _, madebr _, magniff _, marlox-ouda _, mattymo _, mdtrooper _, mgk _, mimi1vx _, mobyte0 _, MonAaraj _, MonthlyPython _, mountainstorm _, mselee _, mwhudson _, naquad _, nchavez324 _, neumond _, nolash _, ntamas _, nyov _, ocarneiro _, okayzed _, pquentin _, rbanffy _, ReddyKilowatt _, regebro _, renegarcia _, rianhunter _, roburban _, RRMoelker _, rwarren _, scopatz _, seanhussey _, seonon _, shadedKE _, sithglan _, Sjc1000 _, sporkexec _, squrky _, ssbr _, techdragon _, thehunmonkgroup _, thisch _, thornycrackers _, TomasTomecek _, tompickering _, tony _, ttanner _, tu500 _, uSpike _, vega0 _, vit1251 _, waveform80 _, Wesmania _, xandfury _, xndcn _, zhongshangwu _, zrax `_

.. |pypi| image:: https://img.shields.io/pypi/v/urwid :alt: current version on PyPi :target: https://pypi.python.org/pypi/urwid

.. |docs| image:: https://github.com/urwid/urwid/actions/workflows/documentation.yml/badge.svg?branch=master :alt: Documentation Status :target: https://urwid.org

.. |gitter| image:: https://img.shields.io/gitter/room/urwid/community :alt: Gitter :target: https://gitter.im/urwid/community

.. |ci| image:: https://github.com/urwid/urwid/actions/workflows/pythonpackage.yml/badge.svg?branch=master :target: https://github.com/urwid/urwid/actions :alt: CI status

.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit :target: https://github.com/pre-commit/pre-commit :alt: pre-commit

.. |coveralls| image:: https://coveralls.io/repos/github/urwid/urwid/badge.svg :alt: test coverage :target: https://coveralls.io/github/urwid/urwid