rich-tree

A beautiful, icon-rich replacement for the classic tree command

Powered by Rich · Nerd Fonts · Python

Open demo.html in a browser for the best preview.

rich-tree demo screenshot

✨ Features

Feature	Description
📁 Compact folders	Squash single nested subdirectories into a single line (enabled by default)
🗂️ 220+ file type icons	Nerd Font glyphs for every major language and tool
🎨 Per-type colors	Brand-accurate colors for every file type
🔗 Clickable links	Files are hyperlinks in supported terminals
📊 File metadata	Show size, created, modified, and accessed timestamps
🌿 Git status overlay	See modified, added, deleted, and untracked files at a glance
🙈 Smart filtering	Reads `.gitignore`, hides dotfiles, supports custom exclusion lists
📁 Depth control	Limit recursion to N levels
🌐 HTML export	Save the styled tree as a shareable HTML file
🧙 Onboarding wizard	Interactive setup guide for fonts and aliases
🖥️ Cross-platform	Windows, macOS, and Linux

📦 Installation

pip install rich-tree

Requires Python 3.6+ and a Nerd Font for icons to render correctly.

With pipx (recommended for CLI tools):

pipx install rich-tree

Run without installing:

pipx run rich-tree .

Development version from GitHub:

pip install git+https://github.com/wasi-master/rich-tree

🚀 Quick Start

# Display tree for the current directory
rtree

# Or use the Python module form
python -m rtree

# Show a specific directory
rtree /path/to/project

Run the interactive onboarding wizard (recommended on first install):

rtree --onboard

This verifies your Nerd Font is set up correctly and walks you through configuration.

📖 Usage

rtree [OPTIONS] [DIRECTORY]

DIRECTORY defaults to . (current directory) if omitted.

Options

Flag	Short	Description
`--compact` / `--no-compact`	`-c`	Squash single nested subdirectories (default: on, alias: `--squash` / `--no-squash`)
`--show-size`	`-ss`	Show file sizes
`--show-created`	`-sc`	Show creation timestamps
`--show-modified`	`-sm`	Show modification timestamps
`--show-accessed`	`-sa`	Show last-accessed timestamps
`--show-git`	`-sg`	Overlay git status on files
`--depth INTEGER`	`-d`	Limit recursion depth (`-1` = unlimited)
`--exclude TEXT`	`-e`	Comma-separated names to exclude
`--ignore-dot`	`-id`	Hide dotfiles
`--all`	`-a`	Show hidden & gitignored files
`--no-gitignore`		Disable `.gitignore` filtering
`--export-html PATH`	`-o`	Save output as HTML
`--width SIZE`	`-w`	Fit output to N characters wide
`--soft`		Enable soft text wrapping
`--onboard`		Run the interactive setup wizard
`--version`	`-v`	Print version and exit

Examples

# Show sizes and git status, 3 levels deep
rtree -ss -sg -d 3

# Show everything — including hidden and gitignored files
rtree --all --no-gitignore

# Exclude build artifacts
rtree -e dist,build,__pycache__

# Export a styled HTML snapshot
rtree -o project-tree.html

# Show all file metadata
rtree -ss -sc -sm -sa

# Shallow view of a project
rtree -d 1 /path/to/project

🧩 Nerd Font Setup

rich-tree uses Nerd Fonts for its icon set. You need to:

Download a Nerd Font from nerdfonts.com/font-downloads
(Recommended: JetBrainsMono Nerd Font, CaskaydiaCove, or FiraCode Nerd Font)
Install the font on your system
Set your terminal's font to the installed Nerd Font

Verify with:

rtree --onboard

If icons appear as □ or ?, follow the instructions shown by the wizard.

🔗 Alias Setup

Replace the classic tree command with rtree for a better experience everywhere:

Bash / Zsh — add to ~/.bashrc or ~/.zshrc:

alias tree="rtree"

PowerShell — add to your PowerShell profile:

New-Alias tree rtree

Windows CMD — create C:\Windows\System32\tree.bat:

@echo off
call rtree %*

Run rtree --onboard for interactive, shell-specific alias instructions.

📚 Documentation

Full documentation is available in the docs/ folder and at the project website:

Document	Description
Getting Started	Installation, requirements, first run
CLI Reference	Every flag and argument explained
Features	Deep dive into all features
Icon System	Complete icon and color reference
Onboarding Wizard	Interactive setup wizard guide
Configuration	Defaults, exclusions, gitignore
Contributing	How to contribute
Changelog	Release history

🛠️ How It Works

rtree .
  │
  ├── Reads .gitignore at each level (hierarchical, full spec support)
  ├── Scans directories with os.scandir() (fast, lazy)
  ├── Resolves icon + color for each entry (name → extension → fallback)
  ├── Optionally fetches git status via git status --porcelain -z
  ├── Optionally reads file stat() for size/timestamps
  └── Renders the Rich Tree widget to the terminal

Dependencies:

Package	Purpose
`rich`	Terminal rendering, Tree widget
`click`	CLI argument parsing
`rich-click`	Beautiful `--help` output
`questionary`	Interactive onboarding prompts
`shellingham`	Shell detection for alias instructions

🤝 Contributing

Contributions are welcome! The most common contribution is adding icons for new file types.

See Contributing Guide for full instructions.

Quick start:

git clone https://github.com/wasi-master/rich-tree.git
cd rich-tree
pip install -e ".[dev]"

📄 License

MIT — © Wasi Master

Documentation · PyPI · Issues · Changelog

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rich_tree-1.1.0.tar.gz (17.1 kB view details)

Uploaded Jul 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

rich_tree-1.1.0-py3-none-any.whl (18.0 kB view details)

Uploaded Jul 20, 2026 Python 3

File details

Details for the file rich_tree-1.1.0.tar.gz.

File metadata

Download URL: rich_tree-1.1.0.tar.gz
Upload date: Jul 20, 2026
Size: 17.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for rich_tree-1.1.0.tar.gz
Algorithm	Hash digest
SHA256	`4a35a6ceef3650f6bc22ffb050a740e3213b04813145f39826c43c189895e62a`
MD5	`5f01d59576516f33ddeb010df301ec9c`
BLAKE2b-256	`fa6db1ae2db402eb3212493df2f14686b13ef348e660c1c03435862fb9f1f3cb`

See more details on using hashes here.

Provenance

The following attestation bundles were made for rich_tree-1.1.0.tar.gz:

Publisher: publish.yml on wasi-master/rich-tree

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: rich_tree-1.1.0.tar.gz
- Subject digest: 4a35a6ceef3650f6bc22ffb050a740e3213b04813145f39826c43c189895e62a
- Sigstore transparency entry: 2206467167
- Sigstore integration time: Jul 20, 2026
Source repository:
- Permalink: wasi-master/rich-tree@05853239734f3f41e1e45776421e3aa62fc6a27f
- Branch / Tag: refs/tags/v1.1.0
- Owner: https://github.com/wasi-master
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@05853239734f3f41e1e45776421e3aa62fc6a27f
- Trigger Event: push

File details

Details for the file rich_tree-1.1.0-py3-none-any.whl.

File metadata

Download URL: rich_tree-1.1.0-py3-none-any.whl
Upload date: Jul 20, 2026
Size: 18.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for rich_tree-1.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`78bbce38e6419bb8677c7693ab615a9d72e3f9f8140b5161e0c01b3f5f4bad8d`
MD5	`924888b67dd86303ea630deb435dfdb8`
BLAKE2b-256	`8fcf8635b0844d322672f0c2f3cd8a6c3356de28ac47ccb97c093834aef89f25`

See more details on using hashes here.

Provenance

The following attestation bundles were made for rich_tree-1.1.0-py3-none-any.whl:

Publisher: publish.yml on wasi-master/rich-tree

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: rich_tree-1.1.0-py3-none-any.whl
- Subject digest: 78bbce38e6419bb8677c7693ab615a9d72e3f9f8140b5161e0c01b3f5f4bad8d
- Sigstore transparency entry: 2206467208
- Sigstore integration time: Jul 20, 2026
Source repository:
- Permalink: wasi-master/rich-tree@05853239734f3f41e1e45776421e3aa62fc6a27f
- Branch / Tag: refs/tags/v1.1.0
- Owner: https://github.com/wasi-master
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@05853239734f3f41e1e45776421e3aa62fc6a27f
- Trigger Event: push

Release history Release notifications | RSS feed

1.1.1

Jul 27, 2026 2 files

This release

1.1.0 This release

Jul 20, 2026 2 files

1.0.1

Jul 7, 2026 2 files

1.0.0

Jul 7, 2026 2 files

rich-tree 1.1.0

rich-tree

✨ Features

📦 Installation

🚀 Quick Start

📖 Usage

Options

Examples

🧩 Nerd Font Setup

🔗 Alias Setup

📚 Documentation

🛠️ How It Works

🤝 Contributing

📄 License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed