structree

structree is a lightweight command-line utility written in Python that generates a visual directory tree, similar to the Unix tree command. The output can be saved to a file or printed directly to the console.

Works on Windows, macOS, and Linux.

---

Features

• Generate a directory tree structure
• Ignore specific files or folders (comma-separated)
• Show only files or only directories
• Output to a file or directly to stdout
• Zero external dependencies — pure Python standard library

---

Installation

Via pip / uv (from PyPI)

pip install structree
# or
uv tool install structree

From source

git clone https://github.com/KaifKol/py-structree.git
cd structree
uv tool install .
# or for development:
uv sync

---

Usage

structree -p <path> [options]

If run without any arguments, the help message is displayed.

Options

Option	Description
-p, --path	Target directory (. , relative, or full path) (required)
-o, --out	Output file name (default: tree.txt)
-i, --ignore	Comma-separated list of files/folders to ignore
-f, --files-only	Show only files
-d, --dirs-only	Show only directories
-s, --stdout	Print output to console instead of writing to a file
--version	Show version number and exit

---

Examples

1. Generate a tree for the current directory

structree -p .

Creates tree.txt inside the target directory.

2. Ignore folders like .git and node_modules

structree -p . -i .git,node_modules

3. Print the tree directly to the console

structree -p . -s

4. Show only files

structree -p . -f

5. Show only directories

structree -p . -d

6. Run as a Python module

python -m structree -p . -s

---

Example Output

Assume the following directory structure:

project/
├── main.py
├── utils.py
├── README.md
└── src/
    ├── core.py
    └── helpers.py

Running:

structree -p project -s

Will output:

project/
├── README.md
├── main.py
├── utils.py
└── src
    ├── core.py
    └── helpers.py

---

Development

# Clone and enter the project
git clone https://github.com/KaifKol/py-structree.git
cd structree

# Create a virtual environment and install dependencies
uv sync

# Run tests
uv run pytest

# Install as a CLI tool (global)
uv tool install .

# Run with uv (no install needed)
uv run structree -p . -s

---

Publishing to PyPI

# Build the package
uv build

# Upload to PyPI
uv publish

---

Notes

• The output uses Unicode box-drawing characters (├──, └──, │)
• Permission errors are silently skipped
• When writing to a file, it is created inside the target directory

---

License

MIT © KaifKol