---
id: textual-universal-directorytree
version: "1.7.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# textual-universal-directorytree — A Textual Directory Tree for all File Systems

License: permissive · Maintenance: aging · Downloads: 194.7K/mo

## What it is and what it does

textual-universal-directorytree is a Textual widget that renders an interactive directory tree in a terminal UI, with the key feature that it works across both local and remote filesystems. It builds on textual's DirectoryTree and extends it through universal-pathlib and fsspec to support S3, Google Cloud Storage, Azure, GitHub, SSH, SFTP, and other fsspec-compatible backends. The widget presents a familiar file-browser interface in the terminal, letting you navigate and select files from any supported filesystem using the same API.

You use it by instantiating UniversalDirectoryTree with a UPath pointing to any supported location—local path, S3 bucket, GitHub repository, or remote SSH server—and adding it to a Textual app's compose layout. The widget handles filesystem abstraction transparently; file selection events return UPath objects compatible with pathlib.Path, so your code can read and process files without caring whether they're local or remote. Optional dependencies unlock support for specific backends, so you only install what you need.

Use it for:

- Browse and preview files in S3 buckets or other cloud storage directly from a terminal UI without switching tools
- Build a terminal-based file manager that works uniformly across local, SSH, and cloud filesystems
- Create a GitHub repository browser in the terminal to explore code and documentation without leaving your editor
- Develop a remote log viewer or data explorer that can read from multiple backends (local, S3, SFTP) in one interface
- Implement a TUI-based deployment or configuration tool that navigates both local and remote file structures

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a DirectoryTree widget for Textual terminal UIs that works with local and remote filesystems including S3, GCS, Azure, GitHub, and SSH through universal-pathlib and fsspec.

Yes, if you are building a Textual terminal UI and need to browse or interact with files across multiple filesystem types. The low install friction, permissive license, and broad filesystem support make it a solid choice for this use case. The aging maintenance status (354 days since last release) is a minor concern but not a blocker given the active repository and lack of known vulnerabilities; monitor for updates if you depend on new features or fsspec backend additions.

## Install

pip install textual-universal-directorytree
uv add textual-universal-directorytree
poetry add textual-universal-directorytree

## Installing textual-universal-directorytree

Before you install: Low friction install with just two runtime dependencies (textual and universal-pathlib). Package is aging—last release 354 days ago—but the repository remains active with recent commits and no archived status.

License in practice: MIT license permits commercial and private use with minimal restrictions; you may use, modify, and distribute the package freely provided you include the license notice.

Quickstart:

pip install textual-universal-directorytree

from textual_universal_directorytree import UniversalDirectoryTree, UPath
from textual.app import App, ComposeResult

class MyApp(App):
    def compose(self) -> ComposeResult:
        yield UniversalDirectoryTree(path=UPath('.'))

Requires Python 3.9 or later. Remote filesystems (S3, GCS, Azure, GitHub, SSH) require optional dependencies like s3fs, gcsfs, adlfs, requests, or paramiko.

Verify before relying:

- Whether the 354-day gap since last release indicates active maintenance or dormancy despite recent commits
- Performance characteristics when browsing large remote filesystems or deeply nested directory structures
- Compatibility testing status across all listed filesystems beyond those documented in the table

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 194.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

textual directory tree widget, remote filesystem browser tui, s3 directory explorer terminal, fsspec file tree display, universal pathlib directory widget, cloud storage file browser, terminal ui file navigation, tui-widget, multi-filesystem, fsspec-plugin

[View on SkillFed](https://skillfed.io/packages/textual-universal-directorytree) · [View on PyPI](https://pypi.org/project/textual-universal-directorytree/)