# How graphviz2drawio Handles Character Encoding for Input Files

> Discover how graphviz2drawio handles character encoding for input files. Learn about system locale detection, explicit CLI flags, and UTF-8 fallback for error-free conversion.

- Repository: [Harold Martin/graphviz2drawio](https://github.com/hbmartin/graphviz2drawio)
- Tags: how-to-guide
- Published: 2026-03-03

---

**graphviz2drawio detects the system locale for default text encoding, supports explicit encoding declarations via CLI flags, and implements automatic UTF-8 fallback to prevent conversion failures.**

The `hbmartin/graphviz2drawio` converter bridges Graphviz DOT files and Draw.io diagrams, requiring robust character encoding handling to process international character sets correctly. Understanding how this tool manages encoding ensures reliable conversion across different operating systems and language locales. The implementation prioritizes flexibility through user overrides while providing sensible defaults based on system configuration.

## Default Encoding Detection via System Locale

In [`graphviz2drawio/models/Arguments.py`](https://github.com/hbmartin/graphviz2drawio/blob/main/graphviz2drawio/models/Arguments.py), the command-line interface defines an `--encoding` (`-e`) parameter that defaults to the system's preferred encoding. The code obtains this value through Python's `locale.getpreferredencoding(do_setlocale=False).lower()`, ensuring cross-platform compatibility without modifying the global locale state.

This approach automatically adapts to Windows systems using `cp1252`, Linux environments defaulting to `utf-8`, or Chinese Windows installations using `gbk`. The default selection happens at argument parse time, making the encoding immediately available to the conversion routine.

## File Reading with Automatic UTF-8 Recovery

The conversion routine in [`graphviz2drawio/__main__.py`](https://github.com/hbmartin/graphviz2drawio/blob/main/graphviz2drawio/__main__.py) opens input files using `Path.open(encoding=encoding)`, passing the encoding parameter directly from parsed CLI arguments. When a `UnicodeDecodeError` occurs and the requested encoding differs from UTF-8, the tool assumes the underlying DOT file is actually UTF-8 encoded—a common scenario on Windows systems with international content.

The fallback logic retries the file read using UTF-8 encoding, preventing conversion failures when the locale-derived default mismatches the actual file encoding. This automatic recovery eliminates manual intervention for files containing Chinese, Japanese, or other non-ASCII characters saved in UTF-8 despite the system's default code page.

## Output Encoding Consistency

After successful parsing and conversion, the generated Draw.io XML maintains encoding consistency by using the same character set that successfully read the input. The write operation in [`graphviz2drawio/__main__.py`](https://github.com/hbmartin/graphviz2drawio/blob/main/graphviz2drawio/__main__.py) applies the final encoding value to the output file, ensuring that international characters survive the round-trip from DOT to XML format.

When users specify `--stdout`, the encoding parameter still governs string handling during conversion, though terminal output may apply additional system-level encoding depending on the shell environment.

## Practical Command-Line Examples

Force UTF-8 encoding regardless of system locale:

```bash
graphviz2drawio -e utf-8 international_graph.dot

```

Handle legacy Windows files using CP1252:

```bash
graphviz2drawio -e cp1252 legacy_graph.dot

```

Process Chinese-language files with GBK encoding:

```bash
graphviz2drawio -e gbk chinese_graph.dot

```

Rely on automatic detection with UTF-8 fallback:

```bash
graphviz2drawio mygraph.dot

```

## Summary

- **System locale detection**: Defaults to `locale.getpreferredencoding(do_setlocale=False).lower()` via [`graphviz2drawio/models/Arguments.py`](https://github.com/hbmartin/graphviz2drawio/blob/main/graphviz2drawio/models/Arguments.py)
- **Explicit overrides**: Supports `--encoding` (`-e`) flag for user-specified character sets like `gbk`, `cp1252`, or `utf-8`
- **UTF-8 fallback**: Automatically retries with UTF-8 when `UnicodeDecodeError` occurs and the original encoding wasn't UTF-8, as implemented in [`graphviz2drawio/__main__.py`](https://github.com/hbmartin/graphviz2drawio/blob/main/graphviz2drawio/__main__.py)
- **Consistent output**: Writes Draw.io XML using the successfully decoded input encoding to preserve character fidelity

## Frequently Asked Questions

### What encoding does graphviz2drawio use by default?

By default, graphviz2drawio uses your system's preferred encoding obtained via Python's `locale.getpreferredencoding(do_setlocate=False).lower()`. This typically returns `utf-8` on Linux and macOS systems, while Windows environments may return `cp1252` or regional code pages depending on the locale configuration.

### How do I convert a DOT file containing Chinese or Japanese characters?

Specify the correct encoding using the `--encoding` or `-e` flag. For files saved in UTF-8 but running on a Windows system with a different default, use `graphviz2drawio -e utf-8 chinese.dot`. For GBK-encoded files common in Chinese Windows environments, use `graphviz2drawio -e gbk chinese.dot`.

### What happens if graphviz2drawio cannot decode the input file?

If the initial encoding attempt raises a `UnicodeDecodeError` and the requested encoding is not UTF-8, graphviz2drawio automatically retries opening the file with UTF-8 encoding. This fallback mechanism handles the common case where DOT files are UTF-8 encoded but the system locale indicates a different code page.

### Does the output XML file use the same encoding as the input DOT file?

Yes, the generated Draw.io XML file uses the same encoding value that successfully decoded the input. The `Path.open()` call in [`graphviz2drawio/__main__.py`](https://github.com/hbmartin/graphviz2drawio/blob/main/graphviz2drawio/__main__.py) applies this encoding to the output stream, ensuring that international characters and special symbols remain intact throughout the conversion process.