Org Chart Generator

Create professional organizational hierarchy charts from structured data. Perfect for company org charts, team structures, reporting relationships, and any hierarchical data visualization.

Quick Start

python

from scripts.orgchart_gen import OrgChartGenerator

# From CSV (employee name + manager)
org = OrgChartGenerator()
org.from_csv("employees.csv", name="name", manager="reports_to")
org.generate().save("org_chart.png")

# From nested dictionary
org = OrgChartGenerator()
org.from_dict({
    'name': 'CEO',
    'children': [
        {'name': 'CTO', 'children': [{'name': 'Dev Lead'}, {'name': 'QA Lead'}]},
        {'name': 'CFO', 'children': [{'name': 'Controller'}]}
    ]
})
org.layout("top-down").generate().save("hierarchy.png")

Features

Multiple Input Sources: CSV, JSON, nested dict, or programmatic
Layout Options: Top-down, left-right, bottom-up, right-left
Node Styling: Colors by level, department, or custom
Additional Data: Titles, departments, photos
Edge Styles: Straight, orthogonal, curved
Export Formats: PNG, SVG, PDF, DOT

API Reference

Initialization

python

org = OrgChartGenerator()

Data Input Methods

python

# From CSV with name and manager columns
org.from_csv(
    filepath="employees.csv",
    name="employee_name",
    manager="reports_to",
    title="job_title",        # Optional
    department="dept",        # Optional
)

# From JSON file (nested structure)
org.from_json("structure.json")

# From nested dictionary
org.from_dict({
    'name': 'Root',
    'title': 'CEO',
    'department': 'Executive',
    'children': [
        {'name': 'Child 1', 'children': [...]},
        {'name': 'Child 2'}
    ]
})

# Programmatic: add nodes and relationships
org.add_node("Alice", title="CEO", department="Executive")
org.add_node("Bob", title="CTO", department="Engineering")
org.add_node("Carol", title="CFO", department="Finance")
org.add_relationship("Bob", "Alice")  # Bob reports to Alice
org.add_relationship("Carol", "Alice")

Layout Configuration

python

# Layout direction
org.layout("top-down")    # TB - Default, root at top
org.layout("bottom-up")   # BT - Root at bottom
org.layout("left-right")  # LR - Root on left
org.layout("right-left")  # RL - Root on right

# Spacing
org.spacing(rank=1.0, node=0.5)  # Vertical and horizontal spacing

Node Styling

python

# Colors by department
org.colors_by_department({
    'Engineering': '#3498db',
    'Finance': '#2ecc71',
    'Marketing': '#e74c3c',
    'Executive': '#9b59b6'
})

# Colors by level (depth in tree)
org.colors_by_level({
    0: '#e74c3c',  # Root (CEO)
    1: '#f39c12',  # Level 1 (C-suite)
    2: '#3498db',  # Level 2 (Directors)
    3: '#2ecc71'   # Level 3+ (Managers/Staff)
})

# Uniform color
org.node_color('#3498db')

# Node shape
org.node_style(
    shape='box',           # box, ellipse, diamond, record
    font='Arial',
    font_size=12,
    border_width=1
)

Edge Styling

python

# Edge style
org.edge_style(
    style='orthogonal',    # orthogonal, straight, curved
    color='#666666',
    width=1.0
)

Generation and Export

python

# Generate the chart
org.generate()

# Save to file
org.save("chart.png")       # PNG
org.save("chart.svg")       # SVG
org.save("chart.pdf")       # PDF
org.save("chart.dot")       # DOT source

# Save with custom size
org.save("chart.png", dpi=150)

# Get DOT source code
dot_code = org.to_dot()

# Show (opens in viewer)
org.show()

Data Formats

CSV Format

Flat structure with manager references:

csv

name,reports_to,title,department
Alice,,"CEO","Executive"
Bob,"Alice","CTO","Engineering"
Carol,"Alice","CFO","Finance"
Dave,"Bob","Dev Lead","Engineering"
Eve,"Bob","QA Lead","Engineering"
Frank,"Carol","Controller","Finance"

Note: Empty reports_to indicates root node(s).

JSON Format

Nested structure:

json

{
  "name": "Alice",
  "title": "CEO",
  "department": "Executive",
  "children": [
    {
      "name": "Bob",
      "title": "CTO",
      "department": "Engineering",
      "children": [
        {"name": "Dave", "title": "Dev Lead"},
        {"name": "Eve", "title": "QA Lead"}
      ]
    },
    {
      "name": "Carol",
      "title": "CFO",
      "department": "Finance",
      "children": [
        {"name": "Frank", "title": "Controller"}
      ]
    }
  ]
}

Dictionary Format

Same nested structure as JSON:

python

data = {
    'name': 'Alice',
    'title': 'CEO',
    'children': [
        {'name': 'Bob', 'title': 'CTO'},
        {'name': 'Carol', 'title': 'CFO'}
    ]
}

CLI Usage

bash

# From CSV
python orgchart_gen.py --input employees.csv \
    --name name --manager reports_to \
    --output org.png

# With title and department
python orgchart_gen.py --input team.csv \
    --name employee --manager boss \
    --title job_title --department dept \
    --layout left-right \
    --output team_chart.png

# From JSON
python orgchart_gen.py --input structure.json --output org.svg

# High resolution
python orgchart_gen.py --input data.csv --name n --manager m \
    --output chart.png --dpi 300

CLI Arguments

Argument	Description	Default
`--input`	Input CSV or JSON file	Required
`--name`	Name column (CSV)	-
`--manager`	Manager column (CSV)	-
`--title`	Title column (CSV)	-
`--department`	Department column (CSV)	-
`--output`	Output file path	`orgchart.png`
`--layout`	Layout direction	`top-down`
`--dpi`	Image resolution	96

Examples

Basic Company Org Chart

python

org = OrgChartGenerator()
org.from_csv("company.csv", name="employee", manager="manager")
org.layout("top-down")
org.node_style(shape='box')
org.generate().save("company_org.png")

Colored by Department

python

org = OrgChartGenerator()
org.from_csv("team.csv", name="name", manager="reports_to", department="dept")
org.colors_by_department({
    'Executive': '#8e44ad',
    'Engineering': '#2980b9',
    'Sales': '#27ae60',
    'Marketing': '#e67e22',
    'HR': '#c0392b'
})
org.layout("left-right")
org.generate().save("dept_org.png")

With Titles

python

org = OrgChartGenerator()
org.from_dict({
    'name': 'Sarah Johnson',
    'title': 'CEO',
    'children': [
        {
            'name': 'Mike Chen',
            'title': 'VP Engineering',
            'children': [
                {'name': 'Lisa Park', 'title': 'Engineering Manager'},
                {'name': 'Tom Brown', 'title': 'Tech Lead'}
            ]
        },
        {
            'name': 'Emma Wilson',
            'title': 'VP Sales',
            'children': [
                {'name': 'John Davis', 'title': 'Sales Manager'}
            ]
        }
    ]
})
org.layout("top-down")
org.generate().save("executive_org.png")

Project Team Structure

python

org = OrgChartGenerator()

# Add nodes
org.add_node("Project Manager", department="PMO")
org.add_node("Tech Lead", department="Engineering")
org.add_node("Designer", department="Design")
org.add_node("Dev 1", department="Engineering")
org.add_node("Dev 2", department="Engineering")
org.add_node("QA", department="Quality")

# Add relationships
org.add_relationship("Tech Lead", "Project Manager")
org.add_relationship("Designer", "Project Manager")
org.add_relationship("QA", "Project Manager")
org.add_relationship("Dev 1", "Tech Lead")
org.add_relationship("Dev 2", "Tech Lead")

org.colors_by_department({
    'PMO': '#9b59b6',
    'Engineering': '#3498db',
    'Design': '#e74c3c',
    'Quality': '#2ecc71'
})
org.generate().save("project_team.png")

Multiple Root Nodes

python

# Board of Directors structure
org = OrgChartGenerator()
org.from_dict({
    'name': 'Board of Directors',
    'children': [
        {
            'name': 'CEO',
            'children': [
                {'name': 'COO'},
                {'name': 'CFO'},
                {'name': 'CTO'}
            ]
        },
        {
            'name': 'Audit Committee',
            'children': [
                {'name': 'Internal Audit'},
                {'name': 'External Audit'}
            ]
        }
    ]
})
org.generate().save("board_structure.png")

Node Display Format

By default, nodes display:

Name (required)
Title (if provided)

Example node appearance:

┌─────────────┐
│  John Smith │
│    CEO      │
└─────────────┘

Dependencies

graphviz>=0.20.0
pandas>=2.0.0

System Requirement: Graphviz must be installed on the system.

macOS: brew install graphviz
Ubuntu: apt-get install graphviz
Windows: Download from graphviz.org

Limitations

Very large org charts (100+ nodes) may be hard to read
Photo support requires external image files
Node positions are auto-calculated (limited manual control)
Complex reporting relationships (matrix orgs) not well supported

Search AI Tools

org-chart-generator

Install this agent skill to your Project

SKILL.md

Org Chart Generator

Quick Start

Features

API Reference

Initialization

Data Input Methods

Layout Configuration

Node Styling

Edge Styling

Generation and Export

Data Formats

CSV Format

JSON Format

Dictionary Format

CLI Usage

CLI Arguments

Examples

Basic Company Org Chart

Colored by Department

With Titles

Project Team Structure

Multiple Root Nodes

Node Display Format

Dependencies

Limitations