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.

📖 Full documentation: https://jsonantt.readthedocs.io

Open the web GUI · Run the GUI locally

Features

• Infinitely nestable tasks — define sub-tasks, sub-sub-tasks, etc., using either tasks or legacy children.
• Composable task files — import task trees from other JSON files with filename, either inline or nested under a wrapper task.
• Auto date computation — parent task start/end are derived automatically from children when not specified.
• Milestone markers — easy "milestone": true flag with chart-level defaults and per-milestone marker overrides, including milestone chains on one row via a date list.
• Major milestones, rollups, and numbering — distinguish major milestones from regular milestones, optionally roll only major milestones up onto summary bars, add milestone edge colours, and label milestones as M1, M2, ... in markers and tables.
• Optional task descriptions and extra fields — add long-form context per task, plus arbitrary metadata like assignee or cost for table output.
• Fully colourable — set colours per-task; children inherit their parent's colour.
• Recursive child colour lightening — inherited subtask colours can optionally lighten at each nested level.
• Clean, indented y-axis labels — task names are left-aligned with proper indentation per depth level.
• Table output mode — render a task summary table with the same hierarchy and colour cues.
• Funded burn output — render cost-over-time charts and period matrix tables from numeric task fields.
• PNG / PDF / SVG output — whatever matplotlib supports.
• Interactive studio — open the GUI or run jsonantt serve for a JSON editor with interactive Gantt, Table, Burn, Burndown, Burnup, and Burn table views.

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",
  "style": {
    "milestone_color": "#FFD700",
    "milestone_marker": "D"
  },
  "tasks": [
    {
      "name": "Phase 1 – Planning",
      "tasks": [
        { "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-24", "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 or table

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
jsonantt -r 1 project.json project.png   # top-level tasks only
jsonantt --renderdepth 2 project.json project.png   # include one child level
jsonantt -t project.json project-table.png   # task name / description table
jsonantt -t project.json project-table.svg   # scalable SVG table
jsonantt -t project.json project-table.csv   # CSV table export
jsonantt --dpi 300 -t project.json project-table.png   # high-resolution PNG table
jsonantt agreed.json compare.png --compare actual.json   # outline vs actual compare chart
jsonantt -t agreed.json compare-table.csv --compare actual.json   # compare table with signed offsets
jsonantt --burn project.json burn.png --burn-field cost --burn-period month --burn-group 0
jsonantt --burn-table project.json burn-table.csv --burn-field cost --burn-period quarter --burn-group 0
jsonantt project.json project.png --date-line today --date-line-color "#C00000"   # single target line

Python API:

See the complete Python and HTTP API reference for every mode, CLI-option mapping, source settings, comparison, and local-file/Git endpoints.

from jsonantt import load_chart, render_burn_chart, render_burn_table, render_chart, render_compare_chart, render_compare_table, render_table

config = load_chart("project.json")
actual = load_chart("actual.json")
render_chart(config, "project.png", dpi=150)
render_chart(config, "summary.png", dpi=150, render_depth=1)
render_table(config, "project-table.png", dpi=150)
render_compare_chart(config, actual, "compare.png", dpi=150)
render_compare_table(config, actual, "compare-table.csv", dpi=150)
render_burn_chart(config, "burn.png", dpi=150, field="cost", period="month", group_by=0)
render_burn_table(config, "burn-table.csv", dpi=150, field="cost", period="quarter", group_by=0)

render_depth=0 renders all nested levels. 1 renders only top-level tasks, 2 includes one level of children, and so on.

--table / -t switches the output to a table view. By default it renders Task, Name, and Description. The Task column keeps hierarchy numbering, the Name column stays unindented, style.table_colorize controls the side color accent, and style.table_show_markers controls whether milestone rows use a diamond marker in that gutter.

You can customize the table columns with style.table_columns. Each entry can be either a string field name or an object with field and optional title. The special fields task, name, and description preserve the existing behavior; any other field is read from the task object, including extra task keys like assignee, cost, or fte.

Column objects can also opt into numeric aggregation. Use rollup: "sum" to show a recursively summed value on parent rows, total: true to add a footer total for that column, and total_level to control which task depth contributes to that footer. When rollup is enabled, totals default to depth 0 so parent rollups are not double-counted.

For display-only unit conversion, set display_factor on the column. This multiplies the numeric value one time at render/export time, after the raw value has been read and after any rollup sum has been calculated. That makes it suitable both for converting FTE into annual dollars and for showing large values in k or M units by pairing a factor with a custom header title.

{
  "style": {
    "table_columns": [
      "task",
      "name",
      { "field": "assignee", "title": "Owner" },
      { "field": "fte", "title": "Annual Cost ($)", "rollup": "sum", "total": true, "total_level": 0, "display_factor": 250000 },
      "description"
    ]
  },
  "tasks": [
    {
      "name": "API Design",
      "start": "2024-01-01",
      "end": "2024-01-10",
      "assignee": "Morgan",
      "fte": 1.2,
      "description": "Finalize endpoints and review contracts."
    }
  ]
}

Examples:

• FTE to annualized dollars: { "field": "fte", "title": "Annual Cost ($)", "display_factor": 250000 }
• Dollars to thousands: { "field": "cost", "title": "Cost (k$)", "display_factor": 0.001 }
• Dollars to millions: { "field": "cost", "title": "Cost ($M)", "display_factor": 0.000001 }

Description and Name cells wrap to the measured rendered width of the column, and the row height expands to fit the wrapped lines. Very long unbroken tokens are not split mid-word, so they can still clip horizontally.

--milestones-only works with --table to render only milestone rows in a dedicated milestone table. --no-milestones does the opposite and excludes milestones.

If the table output path ends in .csv, jsonantt writes CSV instead of an image. .csv output is only accepted for --table/--burn-table modes; Gantt and burn charts must be exported as .png (with --dpi) or .svg, and the CLI reports a clear error for any other extension or combination.

The studio uses this same jsonantt.renderer (matplotlib) code for interactive SVG previews and PNG/SVG/CSV exports. jsonantt serve runs it locally; static hosting runs the bundled Python source in a Pyodide worker.

--compare turns the first JSON input into the planned/agreed baseline and overlays the second JSON as the updated/actual state. In compare charts, planned bars are drawn as slightly larger unfilled outlines, actual bars are drawn normally, removed planned tasks are struck through with no actual bar, and actual-only tasks render as normal filled bars. In compare tables and CSV output, the Offset column shows signed duration changes like +2d, -1w, +3mo, or +1y; milestones use the signed date shift instead.

--burn renders a funded burn chart from a numeric task field such as cost. Burn output always allocates from the lowest tasks that actually carry a numeric value, spreads each task uniformly over its duration, and only then groups the result. That means collapsing to top-level or total views does not lose deeper task spend.

Use --burn-period to choose day, week, month, quarter, or year. Use --burn-group total for one overall series, --burn-group leaf for the lowest direct-cost tasks, or a depth integer where 0 is top-level, 1 is subtasks, 2 is sub-subtasks, and so on. --burn-table renders the same burn data as a matrix with one row per grouped task and one column per time bucket. --burn-display-factor applies a display-only multiplier once, after burn allocation, so the same scaling rules used for cost tables also work here.

--burndown renders remaining planned allocation; --burnup renders cumulative planned allocation with dotted, colour-matched budget lines per task/group:

jsonantt --burndown project.json burndown.png --burn-period quarter
jsonantt --burnup project.json burnup.png --burn-period quarter --burn-group leaf --dpi 300

Use --date-line to draw a single vertical reference line on Gantt, burndown, or burnup outputs. It accepts either a date in the input file's dateformat or the special value today. Use --date-line-color to control its color. The source setting style.today_marker also enables today's marker in these views, including GUI previews and exports. Burn markers appear only within the plotted date range.

Interactive studio

To display cost values as currency in thousands or millions, set optional style fields such as "value_prefix": "$", "value_scale": "millions", and "value_decimals": 2. A raw cost of 1250000 then displays as $1.25M in graphs and tables, including exports. Defaults preserve existing output; raw numbers never change. Configure this in Chart settings → Value display, or see the value-formatting reference.

The CLI also accepts display overrides (without editing your JSON):

jsonantt --burnup project.json burnup.png --value-scale millions --value-prefix '$' --value-decimals 2
jsonantt --burn-table project.json burn.csv --value-scale thousands --value-prefix '$'

Scales are units, thousands, millions, and billions. --value-suffix adds an annotation without scaling; --value-fields cost,budget selects amount fields. For burn views, CLI overrides apply to the selected --burn-field by default. All options are optional; existing output and source values are unchanged.

All six previews use the CLI renderer's SVG directly: Gantt, Table, Burn, Burndown, Burnup, and Burn table. These are interactive SVG elements—not pictures—with task/arrow selection and tooltips. Local instances use Python on the server; static hosting runs the same Python sources in a Pyodide worker. There is no approximate browser drawing fallback. Built-in demos ship with exact, interactive Python-rendered SVG previews. Previously rendered charts restore from a bounded browser cache on refresh, keyed to source, view settings, and renderer build. Python warms up in the background for edits and exports; matplotlib downloads alongside the interpreter. New uncached charts still need the runtime on first use.

Gantt has view controls for Rollup depth and Roll up milestones, saved in the source and shared with exports. Task Properties includes editable Cost in its original units, before any display scaling.

Launch the jsonantt GUI — no installation needed. Try the delivery demo, milestones demo, or cost/burn demo.

For a local instance with PNG/SVG/CSV exports, jsonantt serve opens the same studio — a source sidebar, a live canvas, and a properties/objects side panel, styled after pugflow:

jsonantt serve                  # start with the built-in starter chart
jsonantt serve project.json     # open an existing chart
jsonantt serve --port 8080 --no-browser

• Sidebar — JSON editor with line numbers and syntax highlighting. Every edit re-renders the canvas instantly; parse errors are shown inline without discarding the last good render.
• Canvas tabs — Gantt (default, live-updating) and Table (the same task table the CLI renders, honouring style.table_columns, table_colorize, and table_show_markers). Table filters show all rows, milestones only, or tasks without milestones. Burn shows period-spend bars; separate Burndown and Burnup tabs show remaining and cumulative planned allocation. Burnup includes dotted task/group budget lines. Burn table shows period totals. All share field, period, grouping, and scaling controls. Clicking a bar, milestone, or table row keeps the objects panel and properties box in sync.
• Chart settings — the Settings → Chart settings… dialog exposes the overall chart configuration: title, dateformat, chart start/end (with a calendar date picker), the time scale (major/minor ticks, fiscal calendar), table columns/options, and appearance (colours, row height, render depth, …). Every change rewrites the JSON source, so it persists through the same undo/redo and save flow as any other edit.
• Objects panel — tasks, milestones, and arrows; selecting one highlights it on the canvas.
• Properties box — edit name, id, start, end, duration, not_before, colour, milestone flags, and description. Date fields have a calendar popup that writes dates in the chart's own dateformat. A Relationships section lists what the entry depends on (upstream: not_before, parent, incoming arrows) and what depends on it (downstream: subtasks, chained tasks, outgoing arrows). Every related entry is clickable.
• New adds a task or milestone; Add subtask in task properties creates a child from either Gantt or table view. Set scheduling dependencies with Not before; existing arrows remain editable. Undo/redo, zoom, dark mode, and local PNG/SVG/CSV exports are available.

GUI edits format the source with two-space indentation and a trailing newline. For standalone source formatting, use jsonantt fmt from the command line.

The hosted GUI supports editing, interactive previews, and PNG/SVG/CSV export through Pyodide. Choose File → Export… for PNG/SVG and PNG resolution, or File → Save CSV… in a table view. Open File → Compare… for comparisons: upload any baseline JSON, or use Git history… to select a dated commit (SHA and message included). On the local server, File → Open local file… selects a file by its full path so Git history follows that file, including renames. The baseline is read-only; the current editor is the actual/updated side. Toggle File → Compare mode off to return to ordinary output. While enabled, every existing output tab uses that baseline: Gantt/table use the CLI comparison renderers; burn views show exact baseline/current drawings side by side.

Refresh/revisit restores unsaved source (even temporarily invalid JSON), the current file, view/filter/zoom, comparison baseline, panels, and up to 20 undo/redo entries from browser storage. This does not save to disk. Storage is browser/origin specific; private mode, clearing site data, or storage limits can prevent recovery. Use Save JSON… for a durable copy. An explicit different demo or startup file opens that document instead of restoring the previous workspace.

Run your own local instance

Install Python 3.8 or newer, then create an environment and install jsonantt. On macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade jsonantt
jsonantt serve

On Windows (PowerShell):

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade jsonantt
.\.venv\Scripts\jsonantt.exe serve

The server opens http://127.0.0.1:4174/ in your browser. Keep the terminal running; press Ctrl+C there to stop the server. You can also open http://127.0.0.1:4174/?demo=3 to try the cost demo locally.

jsonantt serve project.json                  # load a chart from disk
jsonantt serve --port 8080 --no-browser       # open http://127.0.0.1:8080/ yourself

For the latest development version, clone this repository, create/activate an environment as above, then install the checkout:

git clone https://github.com/briday1/jsonantt.git
cd jsonantt
python -m pip install -e .
jsonantt serve examples/simple.json

Use File → Save JSON… to download your edits; opening a local chart does not overwrite its file automatically. After updating Python code or upgrading the package, restart the server so exports use the new renderer, then refresh the browser.

To build and serve a static instance (no Python rendering server at runtime):

python -m jsonantt.static_site --output _site
python -m http.server 8080 --directory _site

For immediate first-visit demo previews, build with --prerender (requires Node.js). The Pages workflow enables this automatically. The build bundles the current Python source; do not deploy only jsonantt/web. The Pages workflow performs this build for every Python or GUI change. The browser needs WebAssembly, module workers, and CDN access on first load. If those are unavailable, use jsonantt serve; no alternate chart style is substituted. Rendering data stays in the browser on static hosts.

See the local-server documentation for more options, including access from another device on your network.

jsonantt fmt

jsonantt fmt project.json            # reformat in place
jsonantt fmt project.json -o out.json
cat project.json | jsonantt fmt      # read stdin, write stdout

fmt runs the canonical jsonantt formatter (2-space indent, trailing newline, key order preserved). The studio uses the same formatter, so both paths produce identical files.

JSON reference

Task object

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.

Milestone chains: When milestone: true, date may be either one date string or a list of date strings. A list draws multiple milestone markers on the same task row while keeping the same label, description, color, and marker settings.

Milestone numbering: When style.number_milestones is true, milestones are numbered M1, M2, ... in tree order. The marker keeps its configured shape and the M label is drawn inside it. Tables use the same M labels in the Task column instead of hierarchy numbers for milestone rows.

Milestone rollup: When style.rollup_milestones is true and deeper rows are hidden by render_depth, descendant milestones are not listed as separate rows. Instead their milestone markers are drawn on top of the visible ancestor bar they roll up into. This happens recursively, so deeply nested hidden milestones keep rolling up until they land on a visible row.

Major milestone styling: major_milestone: true implies milestone: true. Major milestones can have a separate default fill, edge colour, marker, and size through the style.major_milestone_* fields. Task-level color, edge_color, marker, and marker_size still override both milestone and major milestone defaults.

Major-only rollup: When both style.rollup_milestones and style.rollup_major_milestones_only are true, hidden regular milestones stay hidden while hidden major milestones roll up onto the visible ancestor bar.

{
  "title": "Release Gates",
  "tasks": [
    {
      "name": "Release Track",
      "tasks": [
        {
          "name": "Gate Reviews",
          "description": "Same milestone row, repeated checkpoints.",
          "milestone": true,
          "date": ["2024-06-01", "2024-06-15", "2024-07-01"],
          "marker": "D",
          "color": "#C0504D"
        },
        {
          "name": "Executive Approval",
          "major_milestone": true,
          "date": "2024-07-08"
        }
      ]
    }
  ]
}

tasks and children are interchangeable at both the chart root and inside nested task objects. If both are present on the same object, jsonantt reads both lists in order.

filename lets you build a larger plan from smaller task files. A task entry that is only { "filename": "phase.json" } inlines the referenced file's tasks at that position. When filename appears alongside normal task fields like name or description, the referenced file's tasks are imported as that task's children. The included file's style, title, chart start/end, and arrows are ignored during inclusion; only its task tree is used.

In the GUI, use File → Append JSON…. Select multiple files (or load a folder for nested includes), check the files to append, reorder them, and choose Append tasks inline or One parent task per file. Click Append selected files to confirm. Files referenced by another selected file are kept available for include resolution but are initially unchecked to avoid importing their tasks twice.

GUI composition uses the CLI's task inclusion rules and converts imported dates to the destination chart's date format. It creates editable snapshots, not live filename links: Save JSON produces one portable document, original files are untouched, and Undo removes an entire append operation. Duplicate task IDs, missing include files, or circular includes leave the current document unchanged. Use filename references in CLI-managed sources when you want live file links.

{
  "title": "Combined Plan",
  "tasks": [
    { "filename": "composed-discovery.json" },
    {
      "name": "Delivery Program",
      "filename": "composed-delivery.json"
    }
  ]
}

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

Style object

Examples

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

Simple project

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

Dependencies

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

Render depth

examples/renderdepth.json — nested tasks that are useful with -r / --renderdepth

Full depth, render_depth=0:

One child level, -r 2:

Top level only, -r 1:

Chained milestones

examples/chained-milestones.json — nested tasks with multiple milestone dates on one row

Composed plans

examples/composed-plan.json — combines multiple task files with filename, including nested chained milestones

Major milestone rollup

examples/major-milestones.json — distinguishes regular vs major milestones, numbers them, and rolls up only hidden major milestones

Table output, -t:

Milestones only, -t --milestones-only:

No milestones, -t --no-milestones:

Try the same file with different depth limits:

jsonantt examples/renderdepth.json examples/renderdepth-all.png      # full depth
jsonantt -r 1 examples/renderdepth.json examples/renderdepth-top.png # top-level only
jsonantt -r 2 examples/renderdepth.json examples/renderdepth-mid.png # one child level
jsonantt -t examples/renderdepth.json examples/renderdepth-table.png # task table view
jsonantt -t --milestones-only examples/renderdepth.json examples/renderdepth-milestones.png # milestones only
jsonantt -t --no-milestones examples/renderdepth.json examples/renderdepth-no-milestones.png # exclude milestones
jsonantt -t examples/renderdepth.json examples/renderdepth-table.csv # CSV table export

Funding burn

examples/funding.json — direct task costs allocated uniformly over time, then grouped into top-level burn output

Monthly burn chart, --burn --burn-period month --burn-group 0:

Quarter burn table, --burn-table --burn-period quarter --burn-group 0:

Color schemes

examples/colors.json — custom palette, background, grid, row band, milestone colours, and custom milestone markers

Compare mode

examples/compare-planned.json and examples/compare-actual.json — planned vs actual comparison with a CLI date line

Compare chart:

Compare table image:

CSV export:

examples/compare-table.csv

Description wrapping

examples/description-wrap.json — demonstrates normal word wrapping in table output and the edge case where a single unbroken token will not wrap

Table output, -t:

CSV export:

examples/description-wrap-table.csv

Custom table fields

examples/costs.json — shows style.table_columns with custom Owner and Cost columns sourced from task fields like assignee and cost

CSV export:

examples/costs-table.csv

Overlapping cost plan

examples/costs-overlap.json — a more realistic cost plan with overlapping workstreams, nested tasks, milestones, and rolled-up Cost (k$) values

Chart output:

Table output, -t:

CSV export:

examples/costs-overlap-table.csv

Monthly burn chart, --burn --burn-period month --burn-group 0 --burn-display-factor 0.001:

Monthly burn matrix, --burn-table --burn-period month --burn-group 0 --burn-display-factor 0.001:

Burn CSV export:

examples/costs-overlap-burn-table.csv

Complex roadmap

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

Table output, -t:

Milestones only, -t --milestones-only:

No milestones, -t --no-milestones:

How to Run

jsonantt examples/simple.json examples/simple.png                    # basic milestones
jsonantt examples/dependencies.json examples/dependencies.png        # not_before scheduling
jsonantt examples/renderdepth.json examples/renderdepth.png          # full nested view
jsonantt -r 1 examples/renderdepth.json examples/renderdepth-top.png # top-level only
jsonantt -r 2 examples/renderdepth.json examples/renderdepth-mid.png # one child level
jsonantt -t examples/renderdepth.json examples/renderdepth-table.png # task table with descriptions
jsonantt -t --milestones-only examples/renderdepth.json examples/renderdepth-milestones.png # milestone table
jsonantt -t --no-milestones examples/renderdepth.json examples/renderdepth-no-milestones.png # table without milestones
jsonantt -t examples/renderdepth.json examples/renderdepth-table.csv # CSV export
jsonantt examples/colors.json examples/colors.png                    # custom palette and background
jsonantt examples/compare-planned.json examples/compare.png --compare examples/compare-actual.json --date-line 2024-03-01 --date-line-color "#C00000" # compare chart with target line
jsonantt -t examples/compare-planned.json examples/compare-table.png --compare examples/compare-actual.json # compare table image
jsonantt -t examples/compare-planned.json examples/compare-table.csv --compare examples/compare-actual.json # compare table CSV
jsonantt -t examples/description-wrap.json examples/description-wrap-table.png # wrapped descriptions table image
jsonantt -t examples/description-wrap.json examples/description-wrap-table.csv # wrapped descriptions CSV
jsonantt -t examples/costs.json examples/costs-table.csv                # custom cost/owner columns CSV
jsonantt examples/complex.json examples/complex.png                  # deep roadmap example
jsonantt -t examples/complex.json examples/complex-table.png         # full complex table
jsonantt -t --milestones-only examples/complex.json examples/complex-milestones.png # complex milestones only
jsonantt -t --no-milestones examples/complex.json examples/complex-no-milestones.png # complex without milestones