Windows Terminal Encoding

Fix UnicodeEncodeError on Windows CMD/PowerShell and get full Rich output

PraisonAI automatically handles Windows legacy code pages to prevent CLI crashes and ensure ASCII-safe output.

from praisonaiagents import Agent

agent = Agent(name="windows-agent", instructions="Handle Unicode output on Windows terminals.")
agent.start("Display this response with proper Unicode encoding on Windows.")

The user sends Unicode text; PraisonAI renders safely without crashing legacy Windows consoles.

Detection Flow

Quick Start

1. Automatic Handling

   PraisonAI ≥ v0.0.x automatically detects legacy Windows code pages and renders ASCII-safe output:

   praisonai --help
   

   No configuration needed - the CLI will work without crashes.

2. Enable Full UTF-8 (Optional)

   For full emoji and box-drawing characters, manually enable UTF-8:

   PowerShell

   $env:PYTHONIOENCODING='utf-8'
   chcp 65001
   praisonai --help
   

   set PYTHONIOENCODING=utf-8
   chcp 65001
   praisonai --help
   

---

How It Works

Component	Behavior	Fallback
Rich Console	Detects legacy code page	Uses ASCII boxes, no emoji
PYTHONIOENCODING	Set to utf-8 for subprocess safety	Prevents child process crashes
Error Handling	Catches UnicodeEncodeError	Shows remediation hint

---

Configuration Options

The automatic encoding detection requires no configuration. However, you can override behavior:

Method	Scope	When to Use
PYTHONIOENCODING=utf-8	Current session	Temporary fix for full Unicode
chcp 65001	Current session	Enable UTF-8 code page
System Environment Variables	Permanent	Set PYTHONIOENCODING globally
Windows Terminal	Best experience	Use modern terminal instead of CMD

---

Common Patterns

Problem: UnicodeEncodeError in Older Versions

Symptom:

UnicodeEncodeError: 'charmap' codec can't encode character '\u2500' in position 0

Solution:

# Temporary fix
set PYTHONIOENCODING=utf-8
praisonai --help

# Or upgrade to latest version
pip install --upgrade praisonai

Pattern: Permanent UTF-8 Setup

For PowerShell users:

# Add to PowerShell profile
Add-Content $PROFILE '$env:PYTHONIOENCODING="utf-8"'

For CMD users:

# Set system environment variable
setx PYTHONIOENCODING utf-8

Pattern: Windows Terminal Integration

Use Windows Terminal instead of legacy CMD:

// Windows Terminal settings.json
{
  "profiles": {
    "defaults": {
      "font": {
        "face": "Cascadia Code"
      }
    }
  }
}

Pattern: Training summary on cp1252

praisonai-train agents handles cp1252/ASCII automatically — the summary table swaps emoji for ASCII (PASSED / *) and falls back to plain-text rows if Rich itself can’t encode. See praisonai-train Package → Windows & non-UTF-8 Consoles for the full flow.

---

Best Practices

Use Windows Terminal for Best Experience

Windows Terminal provides full UTF-8 support and modern terminal features. Download from the Microsoft Store or install via winget install Microsoft.WindowsTerminal.

Set Environment Variables Permanently

Instead of setting PYTHONIOENCODING in each session, add it to your system environment variables through System Properties → Environment Variables.

Consider WSL for Unix-like Experience

Windows Subsystem for Linux (WSL) provides a full Unix terminal experience without encoding issues. Install with wsl --install.

Upgrade to Latest PraisonAI Version

The automatic encoding detection was added in recent versions. Ensure you’re running the latest version with pip install --upgrade praisonai.

---

Related

CLI Reference

Complete CLI command reference

Installation Guide

Getting started with PraisonAI

praisonai-train Package

ASCII-safe training summaries on non-UTF-8 consoles.