yoga-python

Python bindings for Facebook's Yoga layout engine — a cross-platform implementation of CSS Flexbox.

Yoga computes a layout tree of nodes with flexbox styles and outputs pixel-perfect positions. This package wraps the full C++ engine via nanobind, giving you the same layout behavior you get in React Native, Litho, and other Yoga-backed frameworks — directly from Python.

Installation

pip install yoga-python

Building from source requires a C++20 compiler, CMake 3.15+, and nanobind:

pip install scikit-build-core nanobind
pip install .

Quick start

from yoga import (
    Node, Config, Direction, FlexDirection, Justify,
    Align, Edge, YGValuePoint, YGValuePercent,
)

root = Node()
root.flex_direction = FlexDirection.Row
root.width = YGValuePoint(300)
root.height = YGValuePoint(200)
root.set_padding(Edge.All, 10)

child_a = Node()
child_a.flex_grow = 1
child_a.set_margin(Edge.Right, 10)
root.insert_child(child_a, 0)

child_b = Node()
child_b.flex_grow = 2
root.insert_child(child_b, 1)

root.calculate_layout(300, 200, Direction.LTR)

print(f"child_a: {child_a.layout_left}, {child_a.layout_top}, "
      f"{child_a.layout_width}x{child_a.layout_height}")
# child_a: 10.0, 10.0, 90.0x180.0

print(f"child_b: {child_b.layout_left}, {child_b.layout_top}, "
      f"{child_b.layout_width}x{child_b.layout_height}")
# child_b: 110.0, 10.0, 180.0x180.0

API overview

Node

The primary object. Create nodes, configure their styles, build a tree, then call calculate_layout.

node = Node()           # default config
node = Node(config)     # with explicit config

Style properties (set directly as attributes):

Edge-based properties (margin, padding, border, position):

node.set_margin(Edge.Left, 10)           # points
node.set_margin(Edge.Top, YGValuePercent(5))  # percent
node.set_padding(Edge.All, 20)
node.set_border(Edge.Bottom, 1)
node.set_position(Edge.Left, YGValuePoint(50))

Tree manipulation:

node.insert_child(child, index)
node.remove_child(child)
node.remove_all_children()
node.set_children([child_a, child_b])
node.child_count                     # int
node[index]                          # Node (supports indexing)

Layout:

node.calculate_layout(width, height, Direction.LTR)

node.layout_left       # float
node.layout_top        # float
node.layout_width      # float
node.layout_height     # float
node.layout_direction  # Direction
node.layout_margin(Edge.Left)   # float
node.layout_padding(Edge.Top)   # float
node.layout_border(Edge.Right)  # float

Measure functions for leaf nodes with custom content sizing:

def measure(node, width, width_mode, height, height_mode):
    return {"width": 100, "height": 50}

node.set_measure_func(measure)

Baseline functions for custom baseline alignment:

def baseline(node, width, height):
    return height * 0.8

node.set_baseline_func(baseline)

Config

config = Config()
config.use_web_defaults = True
config.point_scale_factor = 2.0
config.errata = Errata.StretchFlexBasis

Values

YGValuePoint(100)       # 100px
YGValuePercent(50)      # 50%
YGValueAuto             # auto
YGValueUndefined        # undefined

Enums

All Yoga enums are available as Python enum types (nanobind enums, int-convertible):

Direction, FlexDirection, Justify, Align, PositionType, Wrap, Overflow, Display, Edge, Unit, MeasureMode, Dimension, BoxSizing, Gutter, Errata, NodeType, LogLevel, ExperimentalFeature

Development

git clone https://github.com/banditburai/yoga-python.git
cd yoga-python
uv sync --dev

# Run tests
uv run pytest tests/ -v

# Lint & type checking
uv run ruff check
uv run ruff format --check
uv run pyright

Test coverage

The test suite is a 1:1 port of the Yoga C++ test suite — 822 tests covering all layout modes, edge cases, and behaviors. Tests that the C++ suite itself skips (GTEST_SKIP) are also skipped in Python.

License

MIT — same as Yoga.