Installation¶

Recursivist is published on PyPI and installs with pip.

Requirements¶

Python 3.10 or higher
pip (or any compatible installer, such as uv)

Recursivist depends on Rich for terminal rendering, Typer for the command-line interface, and shellingham for shell detection. These are installed automatically.

Installing from PyPI¶

pip install recursivist

Installing from Source¶

To get the latest unreleased changes, install from the repository:

git clone https://github.com/ArmaanjeetSandhu/recursivist.git
cd recursivist
pip install -e .

The -e flag installs the package in editable mode, so changes to the source are reflected without reinstalling.

To also install the development tools (pytest, Ruff, mypy, pyright, nox, and others), add the dev extra:

pip install -e ".[dev]"

Verifying the Installation¶

recursivist version

This prints the installed version, e.g. Recursivist version: 2.1.0.

Nerd Font Icons (Optional)¶

By default Recursivist labels files and directories with generic emoji (📄 for files, 📂 for directories with contents, 📁 for empty ones), which render everywhere. It can also use file-type-specific Nerd Font glyphs, which require a patched font installed and selected in your terminal. To switch styles:

recursivist config set icon-style nerd

See Basic Usage for details. If glyphs appear as boxes or question marks, your terminal font is not a Nerd Font; switch back with recursivist config set icon-style emoji.

Terminal Compatibility¶

For the best experience, use a terminal with Unicode and ANSI color support. On Windows, Windows Terminal is recommended. A virtual environment keeps the install isolated from system packages:

python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
pip install recursivist

Next Steps¶

Continue to the Quick Start Guide to start visualizing directory structures.