{"id":8780,"library":"win-unicode-console","title":"win-unicode-console","description":"win-unicode-console is a Python library (current version 0.5) designed to enable proper Unicode input and output within the Windows console for Python versions up to 3.5. It addresses historical encoding issues when running Python scripts directly in the Windows console, allowing for correct display and handling of non-ASCII characters. The library is considered to be in maintenance mode, as Python 3.6 and newer versions have resolved the underlying console encoding issues via PEP 528.","status":"maintenance","version":"0.5","language":"en","source_language":"en","source_url":"https://github.com/Drekin/win-unicode-console","tags":["windows","unicode","console","encoding","python2","python3"],"install":[{"cmd":"pip install win-unicode-console","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Call `enable()` at the very beginning of your script, or via the `python -m run` runner.","symbol":"enable","correct":"import win_unicode_console\nwin_unicode_console.enable()"}],"quickstart":{"code":"import win_unicode_console\n\n# Enable Unicode console support (should be called early)\nwin_unicode_console.enable()\n\n# Now, print Unicode characters\nprint('こんにちは世界 (Hello world in Japanese)')\nprint('Français: bonjour, ça va? (French)')\n\n# Try reading Unicode input (on Python 2, this might still need custom readline hook or specific configurations)\n# For simple testing, focus on output initially.\n# For Python 3, input() typically handles Unicode after enable().\n# Example for Python 3:\ntry:\n    user_input = input('Enter some Unicode text: ')\n    print(f'You entered: {user_input}')\nexcept Exception as e:\n    print(f'Input error: {e}')","lang":"python","description":"This quickstart demonstrates how to enable Unicode support and then print and (for Python 3) read Unicode text in the Windows console. It's crucial to call `win_unicode_console.enable()` early in your script. Ensure your console font (e.g., Lucida Console) supports the characters you wish to display."},"warnings":[{"fix":"Remove `win-unicode-console` from your dependencies for projects targeting Python 3.6 or later.","message":"This package is not necessary for Python 3.6 and newer versions because PEP 528 introduced native UTF-8 support for the Windows console, resolving the underlying issues that `win-unicode-console` addresses. Using it with Python 3.6+ is generally harmless but redundant.","severity":"breaking","affected_versions":"Python 3.6+"},{"fix":"Right-click the console window title bar, select 'Properties' or 'Defaults', navigate to the 'Font' tab, and choose a Unicode-capable font like 'Lucida Console' or 'Consolas'.","message":"Even with `win-unicode-console`, the Windows console must be configured to use a font that supports Unicode characters (e.g., 'Lucida Console' or 'Consolas') to display them correctly. Without a suitable font, characters may still appear as squares or question marks.","severity":"gotcha","affected_versions":"<3.6"},{"fix":"Migrate to the new `streams.enable` or `streams.enable_only` interface, passing stream objects as keyword arguments (e.g., `streams.enable_only(stdin=streams.stdin_text_transcoding)`). For generic use, `win_unicode_console.enable()` should suffice.","message":"Version 0.4 changed the signature of `streams.enable` and removed `streams.enable_reader`, `streams.enable_writer`, and `streams.enable_error_writer`. Code using these older stream-specific functions will break.","severity":"breaking","affected_versions":"<0.4"},{"fix":"Rely on `win_unicode_console.enable()` rather than `chcp 65001` for Unicode support in Python scripts. If you encounter issues, consider using `PYTHONIOENCODING=utf-8` as an environment variable, but be aware of its own potential caveats.","message":"Manually setting the console code page to `chcp 65001` (UTF-8) is often problematic on Windows. It can cause issues with `sys.stdin`, result in `IOError`s, or not fully resolve Unicode display due to limitations of the standard console APIs. `win-unicode-console` is designed to work around these limitations without requiring `chcp 65001`.","severity":"gotcha","affected_versions":"<3.6"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install and call `win_unicode_console.enable()` at the beginning of your script. Additionally, ensure your console font supports the required Unicode characters.","cause":"The default Windows console encoding (e.g., CP437 or CP1252) cannot represent the Unicode character you are trying to print. This is a common issue for Python versions prior to 3.6 on Windows.","error":"UnicodeEncodeError: 'charmap' codec can't encode character '\\uXXXX' in position Y: character maps to <undefined>"},{"fix":"Make sure `win_unicode_console.enable()` is called. Then, change your console font to 'Lucida Console' or 'Consolas' through the console window's properties to ensure full Unicode glyph support.","cause":"This typically indicates either that `win-unicode-console` is not active, or the selected console font does not support the specific Unicode characters being displayed.","error":"Unicode characters display as '?' or squares in the Windows console output."},{"fix":"Review the `win-unicode-console` README for specific `runner` usage (e.g., `py -i -m run` for interactive mode). For Python 2, if `raw_input` issues persist with Unicode, you might need `win_unicode_console.enable(raw_input__return_unicode=False)` if your IPython version is older than 4.","cause":"Prior to version 0.4, `win-unicode-console` used a custom REPL. Changes in 0.4 and later versions refined how the runner works and deprecated certain direct manipulations of `raw_input`. Python 2's `raw_input` returns bytes, which needs careful handling when Unicode is expected.","error":"Scripts launched with `python -m run script.py` (win-unicode-console runner) fail or behave unexpectedly with custom readline hooks or Python 2 `raw_input`."}]}