ltree

ltree is a fast, highly customizable CLI utility used to visualize directory structures in a tree diagram. It features beautiful Rich UI console formatting, robust icon theme support (Nerd Font / Emoji), detailed metrics tracking, and versatile exporters (JSON, YAML, Markdown, HTML, and Graphviz).

>>> ltree tree ltree/core --no-mtime --no-git --no-perm
  📂 core/
  ├── 🐍 __init__.py
  ├── 🐍 config.py
  ├── 📂 filters/
  │   ├── 🐍 __init__.py
  │   ├── 🐍 base.py
  │   ├── 🐍 depth.py
  │   ├── 🐍 folders.py
  │   ├── 🐍 pipeline.py
  │   └── 🐍 sorting.py
  ├── 📂 metadata/
  │   ├── 🐍 __init__.py
  │   ├── 🐍 base.py
  │   ├── 🐍 code.py
  │   ├── 🐍 filesystem.py
  │   ├── 🐍 git.py
  │   ├── 🐍 models.py
  │   ├── 🐍 project.py
  │   ├── 🐍 registry.py
  │   └── 🐍 time.py
  ├── 🐍 models.py
  ├── 📂 scanners/
  │   ├── 🐍 __init__.py
  │   ├── 🐍 aggregation.py
  │   ├── 🐍 filters.py
  │   ├── 🐍 scanner.py
  │   ├── 🐍 sorting.py
  │   ├── 🐍 subtree.py
  │   └── 🐍 traversal.py
  └── 🐍 utils.py

Summary:
Visible:   3 directories,  26 files
Total  :   3 directories,  26 files

Installation

You can install ltree directly from PyPI:

# Using pip
pip install ltree-cli

# Or using uv
uv pip install ltree-cli

For local development or source installations:

# Clone the repository
git clone https://github.com/YuHao-Yeh/ltree.git
cd ltree

# Install in editable mode using uv
uv pip install -e .

# Or using standard pip
pip install -e .

VS Code Extension

ltree now comes with an official VS Code companion!

• Quick Action: Right-click any workspace file or folder in the explorer sidebar to generate a structure diagram.
• Multiple Formats: Select your desired generation format (Markdown List, JSON, Plain Text, or Markdown Code Blocks).
• Customizable: Seamlessly pass any CLI arguments directly from your VS Code Settings or input boxes.
• Convenience: The generated tree diagram will automatically save to your system clipboard for instant sharing.

To get started, check the ltree-vscode directory for detailed installation instructions.

Command-Line Usage

ltree organizes its functionality through logical subcommands.
Run ltree --help to inspect the full list of available subcommands.

1. The tree Subcommand

Generate a directory tree diagram with advanced filtering, metadata inspection, and custom outputs.

# Explicitly generate a tree
ltree tree [path] [options]

# Shortcut fallback (automatically executes the 'tree' subcommand)
ltree [path] [options]

Command Options

Run ltree tree --help to see the full list of available parameters.

Examples

# Display current directory structure
ltree tree

# Output to console with color
ltree tree . -o - --color

# Save tree to a file
ltree tree /path/to/dir -o tree.txt

# For more help
ltree tree --help

Quick Configuration Presets

2. The theme Subcommand

Discovers, lists, or previews available icon mappings.

ltree theme [action] [argument]

Actions & Options

Examples

# Discover what themes are built-in
ltree theme list

# Verify how Nerd Font glyphs render on your terminal environment
ltree theme preview nerd

3. The config Subcommand

Manage configuration files and setting profiles across workspaces.

ltree config [action] [start_path]

Actions & Options

Examples

# Print the merged configuration properties currently in effect.
ltree config show [start_path]

# Trace and locate setting files up through parent directories
ltree config locate [start_path]

# Validate setting syntaxes and formats for setting profiles
ltree config validate [start_path]

Configuration

You can store configuration options in local files to aviod passing them manually on every run. ltree automatically scan upwards for the following configuration targets:

• .ltreerc (JSON formatted configuration)
• pyproject.toml (defined under the [tool.ltree] section)

Precedence Priority

Settings are merged and overridden with the following priority order:

1. Command Line Arguments
2. Local Configuration File (.ltreerc or pyproject.toml)
3. Global Default Configurations

Examples

.ltreerc (JSON)

{
  "theme": "nerd",
  "size": true,
  "human": true,
  "dirs_first": true,
  "exclude": ["dist", "build", "target", "*.log", "*.tmp"]
}

pyproject.toml (TOML)

[tool.ltree]
theme = "emoji"
full_path = true
color = true
size = true
include = ["output", "temp"]

Output Examples

Plain Text (-F text)

ltree/
├── ltree/
│   ├── core.py
│   └── exporters.py
├── tests/
└── README.md

Summary:
Visible:   2 directories,   3 files
Total  :   2 directories,   3 files

Rich UI & Nerd Fonts (-F rich --theme nerd)

 ltree/
├──  ltree/
│   ├──  core.py
│   └──  exporters.py
├──  tests
└──  README.md

Summary:
Visible:   2 directories,   3 files
Total  :   2 directories,   3 files

Markdown Lists (-F md)

• 📂 ltree/
  • 🐍 core.py
  • 🐍 exporters.py
• 📂 tests/
• 📖 README.md

System Architecture

ltree is designed as a modular pipeline, where each stage has a single responsibility.

              CLI
               │
               ▼
    ┌──────────────────────┐
    │     Configuration    │
    └──────────────────────┘
               │
               ▼
    ┌──────────────────────┐
    │       Scanner        │
    │ • Traversal          │
    │ • Filters            │
    │ • Metadata Providers │
    └──────────────────────┘
               │
               ▼
    ┌──────────────────────┐
    │      Tree Model      │
    └──────────────────────┘
               │
               ▼
    ┌──────────────────────┐
    │      Serializer      │
    └──────────────────────┘
               │
               ▼
    ┌──────────────────────┐
    │       Renderer       │
    └──────────────────────┘
               │
               ▼
    ┌──────────────────────┐
    │       Exporter       │
    └──────────────────────┘
               │
               ▼
        Console / File

• Configuration – Resolves command-line arguments and configuration files into a unified TreeConfig.
• Scanner – Traverses the filesystem, applies filters, and collects metadata.
• Tree Model – Stores the scanned directory hierarchy in memory.
• Serializer – Converts the tree model into a renderer-independent representation.
• Renderer – Produces output in the selected format.
• Exporter – Writes the rendered output to the console or a file.

Each layer has a single responsibility and can be extended independently, making ltree easy to customize and maintain.

License

Distributed under the MIT License. See LICENSE for more information.