jsonantt 2026.2

Generate Gantt charts from JSON descriptions using matplotlib

jsonantt

jsonantt generates beautiful Gantt chart images from a simple JSON description.
Charts are rendered with matplotlib so they can be saved as .png, .pdf, .svg, and more.

---

Features

• Infinitely nestable tasks — define sub-tasks, sub-sub-tasks, etc.
• Auto date computation — parent task start/end are derived automatically from children when not specified.
• Milestone markers — easy "milestone": true flag renders a distinctive diamond.
• Fully colourable — set colours per-task; children inherit their parent's colour.
• Clean, indented y-axis labels — task names are left-aligned with proper indentation per depth level.
• PNG / PDF / SVG output — whatever matplotlib supports.

---

Installation

pip install jsonantt

Or, directly from source:

git clone https://github.com/briday1/jsonantt.git
cd jsonantt
pip install -e .

---

Quick start

1. Create a JSON description

{
  "title": "My Project",
  "dateformat": "%Y-%m-%d",
  "tasks": [
    {
      "name": "Phase 1 – Planning",
      "children": [
        { "name": "Requirements", "start": "2024-01-08", "end": "2024-01-19" },
        { "name": "Architecture",  "start": "2024-01-15", "end": "2024-01-31" }
      ]
    },
    { "name": "Planning done", "milestone": true, "date": "2024-01-31" },
    {
      "name": "Phase 2 – Build",
      "color": "#70AD47",
      "children": [
        { "name": "Backend",  "start": "2024-02-01", "end": "2024-03-01" },
        { "name": "Frontend", "start": "2024-02-12", "end": "2024-03-08" }
      ]
    },
    { "name": "Launch", "milestone": true, "date": "2024-04-01", "color": "#FF5757" }
  ]
}

2. Generate the chart

CLI:

jsonantt project.json project.png
jsonantt project.json project.pdf   # vector PDF
jsonantt project.json project.svg   # scalable SVG
jsonantt --dpi 300 project.json project.png   # high-resolution PNG

Python API:

from jsonantt import load_chart, render_chart

config = load_chart("project.json")
render_chart(config, "project.png", dpi=150)

---

JSON reference

Field	Type	Description
title	string	Optional chart title shown at the top
dateformat	string	strptime format string (default: "%Y-%m-%d")
start	date string	Optional chart x-axis start date (overrides task dates)
end	date string	Optional chart x-axis end date
style	object	Visual style overrides (see below)
tasks	array	Top-level list of task objects
arrows	array	Dependency arrows drawn between tasks (see below)

Task object

Field	Type	Description
name	string	Required. Task label
id	string	Unique identifier used for not_before and arrows references
start	date string	Bar start date
end	date string	Bar end date
duration	string or int	Duration from start (or resolved not_before end): "14d", "2w", "3m", "2y", or a plain integer (days)
not_before	string	id of another task — this task starts immediately after that task ends
color	CSS hex string	Bar/milestone colour (e.g. "#4472C4")
milestone	boolean	Render as a diamond milestone instead of a bar
date	date string	Milestone date (used when milestone: true)
marker_size	number	Override milestone diamond size in points
bold	boolean	Render label in bold (top-level tasks are auto-bolded by default)
children	array	Nested sub-tasks (infinitely nestable)

Auto date computation: When a task has children but no explicit start/end, the dates are computed automatically as the earliest child start and latest child end, recursively.

Duration formats: d/day/days, w/week/weeks, m/month/months, y/year/years — e.g. "14d", "2w", "3m", "1y".

Arrow object

Field	Type	Description
from	string	id of the source task (arrow starts at its end)
to	string	id of the target task (arrow points to its start)
color	CSS hex string	Arrow colour (default: "#888888")
label	string	Optional text label drawn on the arrow

Style object

Field	Default	Description
width	14	Figure width in inches
row_height	0.3	Height of each task row in inches
bar_height	0.5	Bar height as a fraction of row_height
font_size	12	Base font size in points
indent_size	3	Spaces added per depth level in labels
label_fraction	0.28	Fraction of figure width used for labels
colors	palette	Array of default hex colours cycled per top-level task
background	"#FFFFFF"	Figure background colour
grid_color	"#E0E0E0"	Vertical gridline colour
row_band_color	"#F5F5F5"	Alternating row band colour
milestone_color	"#E65100"	Default milestone colour
milestone_size	14	Default milestone diamond size in points
major_tick	null	Major tick unit: "year", "quarter", "month", "week"
minor_tick	null	Minor tick unit: "quarter", "month", "week", "day"
major_grid_width	2.0	Major gridline linewidth
minor_grid_width	1.5	Minor gridline linewidth
tick_position	"top"	X-axis label position: "top", "bottom", or "both"
bold_tasks	true	Auto-bold top-level (depth 0) task labels

---

Examples

See the examples/ folder for ready-to-run JSON files.

Simple project

examples/simple.json — a five-phase project with milestones

Complex roadmap

examples/complex.json — a multi-year roadmap with deep nesting and custom colours

Dependencies & arrows

examples/dependencies.json — id, duration, not_before, and arrows

Generate them locally:

jsonantt examples/simple.json examples/simple.png
jsonantt examples/complex.json examples/complex.png
jsonantt examples/dependencies.json examples/dependencies.png

---

License

MIT