tcod

library21.2.0pypypi✓ verified 84d ago

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.

serialization

pip install tcod

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · TCOD

tcod

serializationpythonv21.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tcod

✓ import tcod

No common mistake; import tcod is standard.

tcod.event

✓ from tcod import event

✗ import tcod.event

tcod.event is a module but not a subpackage; use from tcod import event.

KeySym

✓ from tcod.event import KeySym

✗ from tcod import KeySym

KeySym is in tcod.event, not top-level tcod.

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()

Debug

Known issues

breakingEvent 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'].

affects: >=19.6.0

breakingRenderer.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

affects: >=20.0.0

deprecatedTileset.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].

affects: >=20.1.0

gotchaSDL_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.

affects: >=19.5.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'tcod'

tcod package not installed or installed in wrong environment.

fix

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

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

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.*.

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

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

fix

Use 'from tcod.event import KeySym'.

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

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).

Upgrade

Version history

21.2.0latest on PyPI · released Apr 4, 2026

Audit

Dependencies

python-tcodrequiredPyPI package name is 'tcod' but sometimes referred to as 'python-tcod' in documentation; both refer to same package.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/libtcod/python-tcod ↗

packagehttps://pypi.org/project/tcod/ ↗

homepagehttps://python-tcod.readthedocs.io/en/latest/ ↗

docshttps://python-tcod.readthedocs.io ↗

changeloghttps://github.com/libtcod/python-tcod/blob/main/CHANGELOG.md ↗