tcod

21.2.0 verified Sat May 09 auth: no python

The official Python port of libtcod, a library for roguelike game development providing field-of-view, pathfinding, noise, and color handling. Current version is 21.2.0 (requires Python >=3.10), released semi-regularly with support for SDL3, free-threaded Python (3.14t wheels), and event improvements.

pip install tcod

Common errors

error ModuleNotFoundError: No module named 'tcod' ↓

cause tcod package not installed or installed in wrong environment.

fix

Run 'pip install tcod' in your active Python environment.

error AttributeError: module 'tcod' has no attribute 'event' ↓

cause Attempting to use import tcod then tcod.event, but event is a submodule that must be imported explicitly.

fix

Use 'from tcod import event' first, then access event.*.

error ImportError: cannot import name 'KeySym' from 'tcod' ↓

cause KeySym is not in the top-level tcod module; it's in tcod.event.

fix

Use 'from tcod.event import KeySym'.

error tcod.error.TcodError: Could not find a tileset file ↓

cause Tilesheet file path is incorrect or missing.

fix

Provide correct path to a valid tilesheet image (e.g., 'dejavu10x10_gs_tc.png' from tcod's examples).

Warnings

breaking Event key symbols changed: uppercase constants like K_UP are deprecated; use KeySym.UP or KeySym['UP']. Lowercase constants were removed in 19.6.0 but partially restored for PY3.13+. ↓

fix Use tcod.event.KeySym.UP or KeySym["UP"] instead of tcod.event.K_UP. For PY3.13+, KeySym.UP works; for older Python use KeySym['UP'].

breaking Renderer.logical_size returns None instead of (0,0) when unset (tcod 20.0.0+). ↓

fix Check for None before unpacking: logical_size = renderer.logical_size; if logical_size: width, height = logical_size

deprecated Tileset.set_tile and Tileset.get_tile deprecated since 20.1.0, replaced by dict-like access: tileset[codepoint] = tile. ↓

fix Replace set_tile(codepoint, tile) with tileset[codepoint] = tile and get_tile(codepoint) with tileset[codepoint].

gotcha SDL_RENDER_SCALE_QUALITY must be set via os.environ before importing tcod to affect scaling; defaults to nearest since 19.5.0. ↓

fix Set os.environ['SDL_RENDER_SCALE_QUALITY'] = 'linear' before import tcod for linear interpolation scaling.

Imports

tcod
```
import tcod
```
No common mistake; import tcod is standard.
tcod.event
wrong
```
import tcod.event
```
correct
```
from tcod import event
```
tcod.event is a module but not a subpackage; use from tcod import event.
KeySym
wrong
```
from tcod import KeySym
```
correct
```
from tcod.event import KeySym
```
KeySym is in tcod.event, not top-level tcod.

Quickstart

Minimal tcod application: load tileset, create context, print text, and run event loop until quit.

import tcod
import os

def main() -> None:
    tileset = tcod.tileset.load_tilesheet(
        "dejavu10x10_gs_tc.png", 32, 8, tcod.tileset.CHARMAP_TCOD
    )
    with tcod.context.new(
        columns=40,
        rows=30,
        tileset=tileset,
        title="Hello World",
    ) as context:
        console = tcod.Console(40, 30)
        console.print(0, 0, "Hello World")
        while True:
            context.present(console)
            for event in tcod.event.wait():
                if event.type == tcod.event.Quit:
                    raise SystemExit()

if __name__ == "__main__":
    main()