pyletree 2.2.0

Generate directory tree diagrams from the command line

Pyletree

Pyletree is a simple and fast CLI tool to generate directory tree diagrams.

Table of Contents

• Installation
• Usage
• Options
  • General
  • Modes
  • Ordering
  • Display
  • Ignoring
  • Depth
• Examples
• Python API
• Sample Output
• Features
• Release History
• Authors
• License

Installation

From PyPI

pip install pyletree

Local

git clone https://github.com/davi-furtado/pyletree.git
cd pyletree
pip install -e .

Usage

pyletree [ROOT_DIR]

If no directory is provided, the current directory is used:

pyletree

Show help:

pyletree -h

Options

General

• -h, --help Show help message
• -v, --version Show version

Modes

• -do, --dir-only Show directories only
• -fo, --files-only Show files only

Ordering

• -d, --dirs-first List directories before files
• -f, --files-first List files before directories

Alphabetical order is always applied as base sorting.

Display

• -n, --no-pipes Remove vertical pipes between branches

Ignoring

• -g [DIR ...], --git [DIR ...] Ignore .git folder and respect rules from given .git directories or directories containing .git (defaults to current dir if omitted but flag is used)
• -gi [DIR_OR_FILE ...], --gitignore [DIR_OR_FILE ...] Respect .gitignore rules from given paths/dirs (defaults to current dir if omitted)
• -i, --ignore PATTERN [PATTERN ...] Ignore files/directories
• -fi, --filter PATTERN [PATTERN ...] Include only files or directories matching gitignore-style patterns

Depth

• -dl, --depth-level N Limit depth

Examples

Basic:

pyletree

Directories first:

pyletree . -d

Files only:

pyletree . -fo

Limit depth:

pyletree . -dl 2

Dictionary output:

pyletree . -dt -di 4

Ignore entries:

pyletree . -i node_modules dist .git

Filter entries with patterns:

pyletree . -fi *.py docs/

Use .gitignore:

pyletree . -gi

No pipes mode:

pyletree . -n

Python API

You can also use Pyletree programmatically in your own Python code using the FileTree class. It returns an iterable that can also be printed directly:

from pyletree import FileTree

# Create a tree for the current directory
tree = FileTree()

# Print the tree directly
print(tree)

# Or iterate over its lines
for line in tree:
    print(line)

# You can configure it with the same options of the CLI
custom_tree = FileTree(
    root_dir='src/',
    dir_only=True,
    ignore=['__pycache__']
)
print(custom_tree)

Sample Output

Default

project/
│
├── src/
│   ├── main.py
│   └── utils.py
│
├── tests/
│   └── test_main.py
│
└── README.md

No pipes (-n)

project/
├── src/
│   ├── main.py
│   └── utils.py
├── tests/
│   └── test_main.py
└── README.md

Features

• Clean and readable tree output
• .gitignore support (it does not ignore either the .git directory or the .gitignore file; if you want to ignore them, add them to the ignore patterns)
• Custom ignore patterns
• Depth limiting
• Flexible sorting
• Optional compact mode (--no-pipes)

Release History

2.2.0

Enhancements

• -dt/--dict-tree | Enhanced Dictionary Output: improved dictionary format with configurable indentation. Now returns {root: {tree...}} format and supports custom indentation via -di N/--dict-indent N (default 2).
  • Example: pyletree . -dt -di 4 (4-space indentation)
  • Example: pyletree . -dt -di 0 (compact, no indentation)
  • Better structured output for programmatic use

2.1.0

New Features

• -fi/--filter | Include Patterns: display only files and directories matching gitignore-style patterns. Supports multiple patterns and maintains tree hierarchy by including parent directories of matching files.
  • Example: pyletree . -fi *.py src/
  • Smart directory inclusion: shows parent folders even if they don't match the pattern directly
  • Caching optimization for large directory trees

2.0.1

• -g/--git now accepts only directories or .git directories, or directories containing a .git folder.
• -gi/--gitignore continues to accept either a .gitignore file or the containing directory.

2.0.0

Visual & Metadata

• -p/--path-tree | Path Tree: generates a view focused exclusively on the paths of files and directories.
• -o [N] | Text-Only Mode: generates the tree in plain text (without special characters). Accepts an optional parameter N to define the indentation (default: 2 spaces). Can't be used with -n.
• -fs/--file-size | File Sizes: toggle visibility of individual file sizes.
• -ds/--dir-size | Directory Sizes: display cumulative sizes for folders.
• [-b/--big-first | -s/--small-first] | Smart Sorting: order tree entries by size (descending/ascending).

Filtering & Data Structures

• -dt/--dict-tree | Dictionary format: output the tree structure as a native Python dictionary. Use -di N/--dict-indent N for indentation (default 2). Format: {root: {tree...}}
• Global File Filter: support for excluding/including files based on patterns or extensions.
• Add patterns to -i / --ignore option.

API Enhancements

• FileTree.getPath(name): new method to programmatically retrieve the full path of a specific file or directory within the tree.
• Add dict(FileTree) method to convert the tree to a dictionary.
• Add FileTree.getTree() method to convert the tree to a string.
• Add FileTree.getDictTree() method to convert the tree to a dictionary.

1.1.0

• Removed -o / --output-file option
• Added FileTree class for programmatic usage in Python scripts.

1.0.0

• Initial release

Authors

Davi Reis Furtado

Original RP Tree Author: Leodanis Pozo Ramos

License

Pyletree is distributed under the MIT license. See LICENSE for more information.