yml2gantt

Write your project plan in a small YAML file, get a clean gantt chart (PDF, PNG, SVG, …) drawn with matplotlib.

gantt:
  start: 2026-01-05
  duration: 4w

tasks:
  - {name: Write, duration: 2w}
  - {name: Review, start: 2w, duration: 1w}
  - {name: Ship, start: 3w, milestone: true}

yml2gantt plan.yml -o plan.png

Features

• Plain YAML input: easy to write by hand, to diff and to keep in git
• Tasks with subtasks (a task without duration spans its subtasks)
• Milestones, on their own row or placed on a task's bar
• Interrupted tasks: several bar segments on one row
• Custom text in the bars (label), e.g. who works on the task
• Day, week, month, trimester or abstract (numbered) time scales
• Positions as dates or as offsets (3, "2w"), lengths as durations or end dates
• A "we are here" line at today's date or at any position
• Export to any format matplotlib supports (PDF, PNG, SVG, …)
• A Python API to build charts from code, or to draw into your own figures

Installation

Requires Python 3.11 or newer.

pip install yml2gantt

To use only the command line tool, pipx install yml2gantt or uv tool install yml2gantt install it in its own environment.

Command line

yml2gantt examples/project.yml

This draws the chart, saves it as examples/project.pdf and opens a window with it.

yml2gantt examples/workpackages.yml -o plan.png --no-show
python -m yml2gantt examples/sprint.yml     # same thing

On an error in the file (unknown key, bad date, …) the tool prints a message such as yml2gantt: error: task: unknown keys ['durtion'] and exits with status 1.

The YAML format

A file has two sections: gantt (the time axis) and tasks (the rows).

gantt:
  start: 2026-01-05
  duration: 12w
  scale: week
  title: My project

tasks:
  - name: Kick-off
    start: 0
    duration: 3d
    label: Team A                 # text in the bar (default: the name)
    milestones: [Go]              # diamond at the end of the bar

  - name: Development             # no duration: spans its subtasks
    start: 2026-01-12
    subtasks:
      - {name: Backend, start: 0, duration: 4w}
      - {name: Frontend, start: 2w, duration: 5w,
         milestones: [{name: Demo, at: 50%}]}

  - {name: Release, start: 2026-03-20, milestone: true}

Keys are case-insensitive, and task is accepted instead of name. Unknown keys are reported as errors, so typos do not go unnoticed.

Dates, offsets and durations

A position (start, end, a milestone's at) is either a date or an offset. Offsets count from the chart start for tasks, from the parent start for subtasks, and from the task start for segments and milestones. There is no month unit, because months have different lengths: use dates for that.

On the abstract scale, all positions and lengths are plain numbers.

gantt section

Time scales and labels

label_format is a Python format string with these placeholders:

Use \n (in a double-quoted string) for two-line labels, e.g. "{date:%a}\n{date:%d}" or "Q{q}\n{date:%Y}". A period cut to less than half by the chart start or end is left unlabelled.

Tasks and subtasks

• A task without duration/end spans its subtasks (or its segments).
• Tasks take the next color of the matplotlib color cycle. Subtasks use a lighter version of their parent's color, and write their text in the parent's color.
• Subtasks can be milestones too (milestone: true), and get the parent's color.

Milestones

There are two kinds of milestone.

On a task's bar, with milestones (tasks and subtasks):

milestones:
  - Done                    # at the end of the bar
  - {name: Review, at: 40%} # 40% of the bar length
  - {name: Demo, at: 4}     # 4 units after the task start
  - {name: Freeze, at: 2026-02-01, color: tab:red}   # a date

at defaults to 100%. Percentages use the drawn bar, so they also work on a task that spans its subtasks. Milestones are black unless color is given. The label goes to the right of the diamond, or to its left in the last 20% of the chart.

On their own row, with milestone: true: the entry takes only a start (no duration, end, subtasks, segments or milestones) and is drawn as a diamond.

- {name: Grand opening, start: 89, milestone: true, color: tab:red}

Segments

A task interrupted in the middle, or split into phases, can have several pieces of bar on its row:

- name: Field trials
  label: "Team B"           # written in each segment
  start: 2
  segments:
    - {start: 0, duration: 3}               # offsets from the task start
    - {start: 5, end: 8, label: "Retest"}   # own label
  milestones: [Report]      # end of the last segment

The task spans from its start to the end of its last segment: this is what its parent and its percentage milestones use. Touching segments are separated by a thin white line. A task with segments takes no duration/end and no subtasks.

Abstract scale

Use scale: abstract when the chart has no calendar dates, e.g. a project plan in quarters or a course in weeks. All positions and lengths are plain numbers.

gantt:
  start: 0
  duration: 16
  scale: abstract
  step: 1               # one column per unit
  label_format: "Q{n}"  # Q1, Q2, …
  title: Work plan
  now: 5.5              # "we are here": middle of Q6

Examples

Each example in examples/ is commented and shows a different part of the format.

sprint.yml: day scale

house.yml: trimester scale

course.yml: abstract scale

workpackages.yml: abstract scale, work packages

Python API

Building a chart

from yml2gantt import Gantt

g = Gantt(start="2026-01-01", end="2027-01-01", scale="trimester",
          title="Board game launch")

g.add_task("Market research", start=0, duration="6w", label="Alice")

design = g.add_task("Game design", start="2026-02-15")
design.add_subtask("Rules", duration="3w")
proto = design.add_subtask("Prototype", start="3w", duration=60)
proto.add_milestone("Demo", at="50%")

tests = g.add_task("Playtests", start="2026-06-01")
tests.add_segment(duration="3w")
tests.add_segment(start="8w", duration="2w", label="Retest")

g.add_task("Shipping", start="2026-12-15", milestone=True)

fig, ax = g.draw()
fig.savefig("plan.pdf")

Wrong input raises ValueError (or TypeError for a value of the wrong type) with a message naming the task.

Loading YAML from Python

from yml2gantt import Gantt, load_yaml, from_dict

g = load_yaml("examples/project.yml")       # or Gantt.from_yaml(...)
g = from_dict({"gantt": {"start": 0, "duration": 10, "scale": "abstract"},
               "tasks": [{"name": "A", "duration": 4}]})   # or Gantt.from_dict(...)

# Edit it before drawing
g.add_task("Extra task", start=5, duration=2)

Customizing the figure

draw returns plain matplotlib objects, so anything matplotlib can do works afterwards:

import matplotlib.pyplot as plt
from yml2gantt import load_yaml

plt.style.use("seaborn-v0_8-whitegrid")     # styles and the color cycle apply

fig, ax = load_yaml("examples/roadmap.yml").draw(figsize=(14, 6))
ax.set_xlabel("2026 - 2027")
ax.tick_params(axis="y", labelsize=11)
fig.savefig("roadmap.svg", bbox_inches="tight")

To place a gantt inside a larger figure, pass your own axes:

fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(11, 10))
load_yaml("examples/sprint.yml").draw(ax=ax1)
load_yaml("examples/roadmap.yml").draw(ax=ax2)

Limitations

• Subtasks go one level deep (a subtask cannot have subtasks).
• Text in a bar is not shortened: on a short bar, use a short label or label: "".
• Milestone labels can cover the text of their bar: move the milestone (at) or shorten the bar label.
• Dated scales work with whole days (no hours).

Development

git clone https://github.com/ldevillez/yml2gantt
cd yml2gantt
poetry install          # or: pip install -e .
poetry run yml2gantt examples/minimal.yml

Project layout:

yml2gantt/
  cli.py          command line (yml2gantt, python -m yml2gantt)
  model.py        Gantt, Task, segment and milestone objects
  scale.py        time scales: dates → x positions, grid and labels
  io.py           loading from a dict or a .yml file
  plot.py         drawing with matplotlib
  colors.py       color helpers
examples/         example charts
docs/images/      pictures used in this README

Releasing a new version

Releases are made by GitHub Actions (release.yml) when a version tag is pushed. It builds the package, publishes it on PyPI and creates the GitHub release, with the changelog entry as notes.

poetry version minor        # or patch / major: updates pyproject.toml
# move the "Unreleased" notes of CHANGELOG.md under the new version
git commit -am "Release v$(poetry version -s)"
git tag "v$(poetry version -s)"
git push origin main --tags

The release stops if the tag does not match the version in pyproject.toml.

License

MIT