---
id: pytiled-parser
version: "2.2.9"
license: MIT License Copyright (c) 2019 Beefy_Swain Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal… (full text in the JSON record)
license_treatment: permissive
maintenance: aging
---

# pytiled-parser — A library for parsing Tiled Map Editor maps and tilesets

License: permissive · Maintenance: aging · Downloads: 87.6K/mo

## What it is and what it does

pytiled-parser reads Tiled Map Editor files (TMX format) and converts them into Python objects with strict type annotations. It is designed to be engine-agnostic: rather than returning engine-specific types like sprites, it returns standard Python types (Path objects for images, dictionaries for properties), making it compatible with any game framework or custom implementation. The library closely mirrors Tiled's JSON format structure to minimize friction when working with map data.

The package is used to load maps and tilesets into 2D games supporting orthogonal, hexagonal, or isometric layouts. It exposes layers as ordered lists of Layer objects, preserving Tiled's structure while allowing downstream code (like the Arcade library) to reorganize them as needed. Dependencies are minimal: only attrs for data classes and typing-extensions for type hints.

Use it for:

- Load Tiled-authored maps into a 2D game engine or custom game loop without engine-specific bindings.
- Parse tileset definitions to extract tile properties and metadata for procedural level generation.
- Extract layer data from a map to render orthogonal, isometric, or hexagonal tile grids.
- Integrate Tiled map editing workflow into a game development pipeline by reading exported TMX/JSON files.
- Access map object groups and custom properties for game logic (spawn points, collision zones, triggers).

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Parses Tiled Map Editor map and tileset files into strictly typed Python objects, returning standard types like Path objects rather than engine-specific sprites.

Yes. The package is stable (Production/Stable classifier), has zero known vulnerabilities, minimal dependencies, and solves a specific problem—parsing Tiled files—without forcing a particular game engine. The 568-day gap since last release suggests maturity rather than abandonment; the repository remains active. Install it if you use Tiled for level design and need to load maps into Python without engine lock-in.

## Install

pip install pytiled-parser
uv add pytiled-parser
poetry add pytiled-parser

## Installing pytiled-parser

Before you install: Low friction: pure Python wheel with only two lightweight runtime dependencies (attrs and typing-extensions). Repository is active with a recent commit on 2025-04-10, though the last release was 568 days ago, suggesting stable maintenance rather than rapid iteration.

License in practice: MIT License permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects without licensing concerns.

Quickstart:

from pathlib import Path
import pytiled_parser

map_file = Path("assets/maps/my_map.tmx")
my_map = pytiled_parser.parse_map(map_file)

Verify before relying:

- Whether the package handles all Tiled features (custom properties, animations, object groups) or only core map/tileset structures.
- Performance characteristics when parsing large or complex maps.
- Whether parsed objects are fully mutable or read-only after parsing.

## Package facts

- License: MIT License Copyright (c) 2019 Beefy_Swain Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 87.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

tiled map editor parser, tmx file parsing python, tilemap loader, tiled json parser, game map file reader, tileset parser, orthogonal isometric hexagonal maps, game-development, tiled-maps, level-editor

[View on SkillFed](https://skillfed.io/packages/pytiled-parser) · [View on PyPI](https://pypi.org/project/pytiled-parser/)