{"id":8151,"library":"fastkml","title":"Fast KML processing in Python","description":"fastkml is a Python library for creating, parsing, and modifying Keyhole Markup Language (KML) documents. It provides a fast and efficient way to work with KML files, supporting KML 2.2 specification features like Placemarks, Paths, Polygons, and TimeStamp. The current stable version is 1.4.0, and it maintains an active development pace with regular updates.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/cleder/fastkml","tags":["KML","GIS","geospatial","XML","vector data"],"install":[{"cmd":"pip install fastkml","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Required for efficient XML parsing and serialization of KML documents.","package":"lxml"},{"reason":"Used as the underlying geometry model for KML features (Point, LineString, Polygon).","package":"pygeoif"}],"imports":[{"symbol":"KML","correct":"from fastkml import KML"},{"symbol":"Document","correct":"from fastkml.features import Document"},{"symbol":"Placemark","correct":"from fastkml.features import Placemark"},{"symbol":"Folder","correct":"from fastkml.features import Folder"},{"symbol":"Point","correct":"from fastkml.geometry import Point"},{"symbol":"LineString","correct":"from fastkml.geometry import LineString"},{"symbol":"Polygon","correct":"from fastkml.geometry import Polygon"}],"quickstart":{"code":"from fastkml import KML\nfrom fastkml.features import Placemark, Document\nfrom fastkml.geometry import Point\nimport io\n\n# Create a KML object\nk = KML()\nns = '{http://www.opengis.net/kml/2.2}' # KML namespace\n\n# Create a Document and append it to KML\ndoc = Document(ns, 'mydoc', 'My Document', 'This is a sample KML document.')\nk.append_child(doc)\n\n# Create a Placemark and append it to the Document\np = Placemark(ns, 'myplacemark', 'My First Placemark', 'This is a point of interest.')\np.geometry = Point(0, 52.1) # (longitude, latitude)\ndoc.append_child(p)\n\n# Serialize the KML object to a string\nkml_string = k.to_string(prettyprint=True)\nprint(kml_string)\n\n# To parse from a string:\n# kml_parsed = KML()\n# kml_parsed.from_string(kml_string)\n# for feature in kml_parsed.features():\n#     if isinstance(feature, Document):\n#         for sub_feature in feature.features():\n#             if isinstance(sub_feature, Placemark):\n#                 print(f\"Parsed Placemark: {sub_feature.name} at {sub_feature.geometry.coords}\")","lang":"python","description":"This quickstart demonstrates how to create a basic KML document containing a single Placemark with a Point geometry, and then serialize it to a string. It also includes commented-out code showing how to parse a KML string back into objects."},"warnings":[{"fix":"Ensure geometry objects are `pygeoif` types. If you have a `shapely.geometry.Point`, construct a `fastkml.geometry.Point` (which is a `pygeoif` object) from its coordinates, e.g., `p.geometry = Point(shapely_point.x, shapely_point.y)`.","message":"fastkml uses `pygeoif` objects for geometries (e.g., `fastkml.geometry.Point`). Users accustomed to `shapely` geometries directly will need to convert them to `pygeoif` objects before assigning them to `fastkml` features. While `shapely` objects can often be used to create `pygeoif` objects, direct assignment of `shapely` types will fail.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always pass the KML namespace `ns = '{http://www.opengis.net/kml/2.2}'` as the first argument when instantiating KML objects like `Document(ns, ...)` or `Placemark(ns, ...)`.","message":"The KML specification requires XML namespaces. When creating KML elements (e.g., `Document`, `Placemark`), you must pass the correct namespace string, typically `{http://www.opengis.net/kml/2.2}`. Forgetting this can lead to malformed KML or issues when parsing with other tools.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate any usage of `fastkml.alt_kml` to the standard `fastkml.KML`, `fastkml.features`, and `fastkml.geometry` modules. The API changed significantly, so refer to the 1.0.0+ documentation for the correct approach.","message":"The `fastkml.alt_kml` module and its classes were deprecated in version 1.0.0. This module provided an alternative, less-standardized way to create KML elements and is no longer recommended or supported.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Convert your geometry to a `pygeoif` object first. For example, if you have a `shapely_point = shapely.geometry.Point(0, 0)`, create `fastkml_point = fastkml.geometry.Point(shapely_point.x, shapely_point.y)` and assign `placemark.geometry = fastkml_point`.","cause":"Attempting to assign a geometry object from a different library (e.g., `shapely.geometry.Point`) directly to a fastkml feature's `.geometry` attribute, instead of a `pygeoif` (fastkml's internal) geometry object.","error":"AttributeError: 'Point' object has no attribute 'kml_tag' (or similar geometry attribute error)"},{"fix":"Verify the KML content for correctness and ensure it's a well-formed XML document conforming to the KML specification. Check for correct encoding (usually UTF-8) and ensure the file/string isn't empty.","cause":"The input string or file provided to `kml.from_string()` or `kml.from_file()` is not valid KML XML, or it's empty, malformed, or has incorrect encoding.","error":"fastkml.exceptions.KmlError: Not a valid KML document (or lxml.etree.XMLSyntaxError)"},{"fix":"For files, ensure you're passing an opened file handle (e.g., `with open('my.kml', 'rb') as f: k.from_file(f)`). For strings, ensure the data is truly a string or bytes. If you have a file path, open it first.","cause":"When using `kml.from_file()`, an opened file *object* should be passed, not a file path. When using `kml.from_string()`, a string or bytes object should be passed.","error":"TypeError: expected string or bytes-like object, got _io.BufferedReader (or similar type error during parsing)"}]}