Skip to main content

file_tree_display

A utility for generating a visually structured directory tree.

Modules

file_tree_display.py

This core module supports recursive traversal, customizable hierarchy styles, and inclusion / exclusion
patterns for directories and files.
Output can be displayed in the console or saved to a file.

Key Features

  • Recursively displays and logs directory trees
  • Efficient directory traversal
  • Blazing fast (see Benchmarks below)
  • Generates human-readable file tree structure
  • Supports including / ignoring specific directories or files via pattern matching
  • Customizable tree display output
  • Optionally saves the resulting tree to a text file
  • Lightweight, flexible and easily configurable

Benchmarks

Class Overview

FileTreeDisplay Constructs and manages the visual representation of a folder structure of a path or of a disk drive.

Initialization Parameters

Parameter Type Description
root_dir str Path to the directory to scan.
filepath str / None Optional output destination for the saved file tree.
ignore_dirs list[str] or set[str] or None Directory names or patterns to skip.
ignore_files list[str] or set[str] or None File names or patterns to skip.
include_dirs list[str] or set[str] or None Only include specified folder names or patterns.
include_files list[str] or set[str] or None Only include specified file names or patterns, '*.pdf' - only include pdfs.
style str Characters used to mark hierarchy levels. Defaults to 'classic'.
indent int Number of style characters per level. Defaults 2.
files_first bool Determines whether to list files first. Defaults to False.
skip_sorting bool Skip sorting directly, even if configured.
sort_key_name str Sort key func name. Natural, Lexicographic or custom. Defaults to 'natural'.
reverse bool Reversed sorting order.
custom_sort Callable[[str], Any] / None Custom sort key function.
title str Custom title shown in the output.
save2file bool Save file tree (folder structure) info into a file.
stream_output bool Stream print tree content without building a buffer.
printout bool Print the generated tree to stdout.
entry_count bool Show number of scanned subfolders and files. Defaults to False.

Core Methods

  • file_tree_display(save2file: bool = True) -> str | None
    Generates the directory tree. If save2file=True, saves the output; otherwise prints it directly.

  • _build_tree(dir_path, *, prefix, style, sort_key, files_first, dir_filter, file_filter, reverse) -> Generator[str, None, None]
    Yields formatted lines representing the directory tree rooted at dir_path using a recursive DFS.

Parameter Type Description
dir_path str Path to the directory being traversed.
prefix str Current indentation prefix for nested entries.
style dict[str, str] Connector style mapping with keys: branch, end, space, and vertical.
sort_key Callable[[str], Any] Function used to sort directory and file names.
files_first bool If True, list files before subdirectories.
dir_filter, file_filter Callable[[str], bool] Predicates to include or exclude directories and files.
reverse bool If True, reverses the sort order.

Example Usage

from pathlib import Path
from file_tree_display import FileTreeDisplay

root = r'c:/your_root_dir'
target_path = r'c:/your_target_path'
filename = 'filetree.md'
filepath = str(Path(target_path, filename))

ftd = FileTreeDisplay(root_dir=root,
                      ignore_dirs=['.git', 'node_modules', '.idea'],
                      ignore_files=['.gitignore', '*.toml'], 
                      style='classic',
                      include_dirs=['src', 'tests', 'snapshots'],
                      filepath=filepath, 
                      sort_key_name='custom',
                      custom_sort=(lambda x: any(ext in x.lower() for ext in ('jpg', 'png'))),
                      files_first=True,
                      reverse=True
                     )
ftd.file_tree_display()

Custom connector style

You can define and register your own connector styles at runtime by adding entries to style_dict:

from file_tree_display import FileTreeDisplay
ftd = FileTreeDisplay(root_dir=".")
ftd.style_dict["plus2"] = ftd.connector_styler("+-- ", "+== ")
ftd.style = "plus2"
ftd.printout = True
ftd.file_tree_display()

FTD CLI — File Tree Display

The FTD CLI (ftd) is a lightweight, configurable command-line tool for displaying or exporting a formatted file tree of a given directory.
It’s designed for flexibility, allowing users to control inclusion/exclusion rules, visual style, sorting behavior, and output options.


Features

  • Generate a clean, formatted file tree of any directory
  • Choose from multiple connector styles (classic, dash, arrow, plus)
  • Fine-grained control over included/excluded files and directories
  • Flexible sorting modes (natural, lex, or custom)
  • Optionally export the tree to a file or print directly to stdout
  • Supports configuration via JSON config file

Usage

ftd [OPTIONS]

Example:

ftd --root-dir ./src --style arrow --files-first --printout --entry-count

This displays the tree structure of the src directory using the arrow connector style, listing files before directories, and prints the output to the console.


Command-Line Options

Option Alias Type Description Default
--cfg – str Path to a JSON configuration file. –
--root-dir -r str Root directory to display. –
--filepath -o str Output file path for exported tree. –
--ignore-dirs – str… Directories to exclude from the tree. –
--ignore-files – str… Files to exclude from the tree. –
--include-dirs – str… Directories to explicitly include. –
--include-files – str… Files to explicitly include. –
--style -s str Tree connector style (classic, dash, arrow, plus). classic
--indent -i int Indent width (spaces) per directory level. 2
--files-first -f flag List files before directories. False
--skip-sorting – flag Disable sorting altogether. False
--sort-key – str Sorting key: natural or lex. natural
--reverse – flag Reverse the sort order. False
--no-save – flag Do not save output to file. False
--stream-output -stream flag Stream tree content without building a buffer. False
--printout -p flag Print the generated tree to stdout. False
--entry-count flag Show number of scanned subfolders and files. False
--version -v flag Show the current version of FTD and exit. –

Configuration via JSON file

FTD can also load parameters from a JSON config file:

{
  "root_dir": "./project",
  "ignore_dirs": ["__pycache__", "build"],
  "ignore_files": [".DS_Store"],
  "style": "dash",
  "files_first": true,
  "printout": true,
  "entry_count": true
}

Run it using:

ftd --cfg path/to/config.json

Command-line arguments always override config file values.


Examples

Display the current directory with default settings:

ftd

Display a tree with dashed connectors, ignoring test folders, and print it:

ftd -r ./src --ignore-dirs tests --style dash --printout

Streaming out tree content, skipping buffer filling, file creation and entries counting:

ftd -stream

Export a formatted tree to a file:

ftd -r ./app --filepath tree.txt

Reverse lexical sort with 4-space indentation:

ftd -r ./data --sort-key lex --reverse --indent 4

Output Example

nano_dev_utils/
├── src/
│ └── nano_dev_utils/
│   ├── __init__.py
│   ├── __version__.py
│   ├── _constants.py
│   ├── common.py
│   ├── dynamic_importer.py
│   ├── release_ports.py
│   └── timers.py
├── tests/
│ ├── test_timers/
│ │ ├── __init__.py
│ │ ├── conftest.py
│ │ ├── test_duration_formatter.py
│ │ ├── test_timer.py
│ │ └── test_timers_async.py
│ ├── __init__.py
│ ├── test_common.py
│ ├── test_dynamic_importer.py
│ └── test_release_ports.py
├── .gitignore
├── .pre-commit-config.yaml
├── LICENSE
├── pyproject.toml
├── README.md
├── ruff.toml
├── update_package.py
└── uv.lock
Scanned 4 subfolders and 24 files.

Unicode Output Notes



License

This project is licensed under the MIT License. See LICENSE for details.

Metadata

Release files for file-tree-display 1.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for file-tree-display 1.3.1
File Size Uploaded Provenance Actions
file_tree_display-1.3.1.tar.gz 65.2 kB Without provenance Details for file_tree_display-1.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for file-tree-display 1.3.1
File Interpreter ABI Platform Actions
file_tree_display-1.3.1-py3-none-any.whl Python 3 none any Details for file_tree_display-1.3.1-py3-none-any.whl

Total release size: 78.9 kB

Release files / file_tree_display-1.3.1.tar.gz

Download URL file_tree_display-1.3.1.tar.gz
Size 65.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ec436d9f6e31de320c05b7411e1c24d5dae9f0ab8d65b182bb71581074588df7
BLAKE2b-256 checksum
How to use checksums
6fc280c53af220e6dd20f43e0786ad3b15564266c7168fd577cbdbcb7346e189
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / file_tree_display-1.3.1-py3-none-any.whl

Download URL file_tree_display-1.3.1-py3-none-any.whl
Size 13.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7adc813595042c5dc95964c31ca91d77858775c7e80cec26762955ee369f0e95
BLAKE2b-256 checksum
How to use checksums
1877f9daa8e869e4c0f4b2bc8560eada3939b5a70bc406fb2d919817097e8c98
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for file-tree-display 1.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page