Metadata-Version: 2.4
Name: xefm
Version: 1.10.0
Summary: XeFM — a dual-pane file manager for the desktop and the terminal
Author: craftware
License-Expression: MIT
Project-URL: Homepage, https://crftwr.github.io/xefm/
Project-URL: Repository, https://github.com/crftwr/xefm
Project-URL: Issues, https://github.com/crftwr/xefm/issues
Project-URL: Extensions, https://github.com/crftwr/xefm/wiki/Extensions
Keywords: file manager,dual-pane,orthodox file manager,desktop,terminal,tui,keyboard,sftp,s3,archive,extensions
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: puikit>=1.14.0
Requires-Dist: pygments
Requires-Dist: boto3
Requires-Dist: watchdog
Requires-Dist: pillow
Requires-Dist: libarchive-c
Requires-Dist: pymigemo==0.0.1
Requires-Dist: doc-files[pdf]>=0.1.0
Requires-Dist: similar-files[image]>=0.2.1
Requires-Dist: comtypes; sys_platform == "win32"
Requires-Dist: truststore>=0.10; sys_platform == "darwin" or sys_platform == "win32"
Dynamic: license-file

<!-- Generated from README.md by tools/gen_pypi_readme.py; relative
     links rewritten against the v1.10.0 tag for PyPI. Do not edit
     or commit. -->

# XeFM — a dual-pane file manager for the desktop and the terminal

XeFM — short for *Xenolith File Manager* — is a keyboard-driven dual-pane file manager that runs as a native desktop application on **Windows and macOS**, and in the terminal on **Windows, macOS, and Linux**. SSH servers, S3 buckets and archives open like any folder, and almost everything is yours to change in Python: install [ready-made extensions](https://github.com/crftwr/xefm/wiki/Extensions), write your own, or ask an AI coding agent to write one with [the XeFM skill](https://github.com/crftwr/xefm/blob/v1.10.0/doc/AGENT_SKILL_FEATURE.md).


![title](https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/xefm-page-title.jpg)

<table>
  <tr>
    <th width="50%">GUI (macOS)</th>
    <th width="50%">TUI</th>
  </tr>
  <tr>
    <td>

https://github.com/user-attachments/assets/f121401d-990b-445d-aa79-526d34e4a44e

</td>
    <td><img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/xefm-tui-demo.gif" alt="XeFM in the terminal: browsing, viewers, search, directory compare and themes"></td>
  </tr>
</table>

## Key Features

- **Cross-platform** - Native desktop app on **Windows and macOS**; terminal (TUI) app on **Windows, macOS, and Linux**
- **Dual-pane interface** with independent navigation and cross-pane operations
- **Archive browsing** - Navigate ZIP, TAR, and compressed archives as virtual directories
- **SFTP support** - Browse and manage remote servers via SSH with optimized performance
- **AWS S3 support** for cloud storage operations
- **Connect to Server** - Find file servers on the network, browse their shares, and mount one from inside XeFM, with no Finder or Explorer detour (macOS and Windows)
- **Advanced search** with real-time filtering, background processing, and multi-selection bulk operations
- **Rich built-in viewers** - Syntax-highlighted text, images, Markdown, JSON, and CSV/TSV
- **Themes & visual effects** - A dozen built-in themes; desktop mode adds GPU background animations, CRT/phosphor screen effects, and text-reveal animations
- **Customizable** - Fully configurable key bindings, settings, and external program launchers; a command palette finds every action by name
- **Extensions** - Install packages that add actions, themes, filters, syntax highlighting and more — [browse the list](https://github.com/crftwr/xefm/wiki/Extensions) — or let an AI agent write one with the XeFM skill

## Quick Start

### Installation

Pick the install that matches how you want to run XeFM:

| | Get it from | Gives you |
|---|---|---|
| **Desktop app** — Windows | the **[Microsoft Store](https://apps.microsoft.com/detail/9PK2X44W810V)** | A real installed application, signed by Microsoft: one click, automatic updates, no SmartScreen prompt. No Python needed. |
| **Desktop app** — macOS | the [latest release](https://github.com/crftwr/xefm/releases/latest), or Homebrew: `brew install --cask crftwr/tap/xefm` | A real installed application: own icon, Dock entry, own file permissions. No Python needed. |
| **Terminal app** — Windows, macOS, Linux | [PyPI](https://pypi.org/project/xefm/) | The `xefm` command in any terminal, including over SSH. Needs Python 3.10+. |
| **Terminal app** — macOS, Linux | Homebrew: `brew install crftwr/tap/xefm` | The same `xefm` command, managed by Homebrew. Use PyPI instead if you want to add Python libraries of your own. |

The desktop and terminal apps coexist and share their settings in `~/.xefm/` —
installing both is a perfectly normal setup.

### Desktop app (Windows, macOS)

The desktop packages bundle their own Python, so there is nothing else to install.

**Windows** — install from the
**[Microsoft Store](https://apps.microsoft.com/detail/9PK2X44W810V)**, or run
`winget install --id 9PK2X44W810V --source msstore`: XeFM lands in the Start
menu, updates automatically, and uninstalls from *Settings → Apps*. An unsigned
**portable zip** also ships with every
[release](https://github.com/crftwr/xefm/releases/latest); it needs
[unblocking once](https://github.com/crftwr/xefm/blob/v1.10.0/doc/DESKTOP_MODE_GUIDE.md#windows--the-portable-zip).

**macOS** — download `XeFM-<version>-macos.dmg` from the
**[latest release](https://github.com/crftwr/xefm/releases/latest)**, drag
**XeFM** to *Applications*, and launch it from Launchpad or Spotlight. It is
signed with the author's Apple Developer ID. Or let Homebrew install and
upgrade it:

```bash
brew install --cask crftwr/tap/xefm
```

Full install details, including Gatekeeper notes, are in the
**[Desktop Mode Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/DESKTOP_MODE_GUIDE.md#installing-the-desktop-app-package)**.

> **Use the package, not `xefm --backend gui`** — that path is for developing
> XeFM, not for using it: the Dock / taskbar icon and, on macOS, the file
> permissions get attributed to Python / your terminal instead of to XeFM. See
> [Why not `xefm --backend gui`?](https://github.com/crftwr/xefm/blob/v1.10.0/doc/DESKTOP_MODE_GUIDE.md#why-not-xefm---backend-gui).

### Terminal app (Windows, macOS, Linux)

XeFM is on [PyPI](https://pypi.org/project/xefm/). Install it as a tool and run
it — no checkout and no virtualenv to manage:

```bash
pipx install xefm     # or:  uv tool install xefm,  or:  pip install xefm
xefm
```

[pipx](https://pipx.pypa.io) and [uv](https://docs.astral.sh/uv/) keep XeFM in
its own environment while putting the `xefm` command on your PATH; `uvx xefm`
tries it once without installing anything. Python 3.10+ is the only
prerequisite — the install for SSH sessions, remote servers, and
terminal-centric workflows.

On macOS and Linux, Homebrew can install the terminal app instead:

```bash
brew install crftwr/tap/xefm
```

If your `config.py` imports a library XeFM doesn't ship, or you want a Pillow
plugin such as `pillow-heif`, list it in `~/.xefm/requirements.txt` and run
`xefm deps sync` (or Tools → Advanced → Sync Python Packages). That works the same for
every install, the desktop apps included, and survives upgrades. See
[Extra Python Libraries](https://github.com/crftwr/xefm/blob/v1.10.0/doc/PYTHON_PACKAGES_FEATURE.md).

**Upgrade with the same tool you installed with** (`pipx upgrade xefm`,
`uv tool upgrade xefm`, `pip install --upgrade xefm`, or `brew upgrade xefm`) — they are not
interchangeable. Details and fixes for common install errors are in the
[User Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/XEFM_USER_GUIDE.md#upgrading-and-uninstalling).

### From source

Working on XeFM itself? Use a checkout instead:

```bash
git clone https://github.com/crftwr/xefm.git
cd xefm
make venv        # creates .venv with every dependency
make run         # launch XeFM through it, no activation needed
```

`make help` lists the rest — editable install, PuiKit co-development, and the
macOS / Windows app bundles.

### Essential Controls

- **Navigate:** `↑↓` to move up/down, `←→` to switch panes/navigate directories
- **Select:** `Space` to select/deselect files, `A` for all files, `Shift-A` for all items
- **File operations:** `C` (copy), `M` (move), `K` (delete), `R` (rename)
- **Search:** `F` for incremental search, `Shift-F` for filename search, `Shift-G` for content search
- **Remote paths:** open `ssh://hostname/path` or `s3://bucket/path` like any directory
- **Help:** `F1` opens the help dialog with every key binding organized by category — no need to memorize
- **Quit:** `Q` to exit

## Documentation

### User Documentation
- **[Complete User Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/XEFM_USER_GUIDE.md)** - Comprehensive guide covering all features, configuration, and usage
- **[Configuration](https://github.com/crftwr/xefm/blob/v1.10.0/doc/CONFIGURATION_FEATURE.md)** - Complete configuration reference and customization guide
- **[Desktop Mode](https://github.com/crftwr/xefm/blob/v1.10.0/doc/DESKTOP_MODE_GUIDE.md)** - Native Windows / macOS desktop app setup and options
- **[Color Schemes & Visual Effects](https://github.com/crftwr/xefm/blob/v1.10.0/doc/COLOR_SCHEMES_FEATURE.md)** - Themes, themeable GPU background scenes, and screen effects
- **[Image Viewer](https://github.com/crftwr/xefm/blob/v1.10.0/doc/IMAGE_VIEWER_FEATURE.md)**, **[Markdown Viewer](https://github.com/crftwr/xefm/blob/v1.10.0/doc/MARKDOWN_VIEWER_FEATURE.md)** & **[JSON / CSV Viewers](https://github.com/crftwr/xefm/blob/v1.10.0/doc/JSON_CSV_VIEWERS_FEATURE.md)** - Built-in viewers
- **[Diff Viewer](https://github.com/crftwr/xefm/blob/v1.10.0/doc/DIFF_VIEWER_FEATURE.md)** & **[Batch Rename](https://github.com/crftwr/xefm/blob/v1.10.0/doc/BATCH_RENAME_FEATURE.md)** - File / directory diffs and regex-based multi-file renaming
- **[SFTP Support](https://github.com/crftwr/xefm/blob/v1.10.0/doc/SFTP_SUPPORT_FEATURE.md)** - Remote server access via SSH with file operations and search
- **[AWS S3 Support](https://github.com/crftwr/xefm/blob/v1.10.0/doc/S3_SUPPORT_FEATURE.md)** - Cloud storage integration and S3 bucket management
- **[Connect to Server](https://github.com/crftwr/xefm/blob/v1.10.0/doc/CONNECT_TO_SERVER_FEATURE.md)** - Mount SMB / WebDAV shares, and disconnect or eject volumes, without leaving XeFM
- **[Archives](https://github.com/crftwr/xefm/blob/v1.10.0/doc/ARCHIVE_FEATURE.md)** - Create, extract, and browse archives as directories
- **[Migemo Search](https://github.com/crftwr/xefm/blob/v1.10.0/doc/MIGEMO_SEARCH_FEATURE.md)** - Japanese matching from typed romaji in incremental search
- **[Search Animation](https://github.com/crftwr/xefm/blob/v1.10.0/doc/SEARCH_ANIMATION_FEATURE.md)** - Advanced search features and visual feedback
- **[Folder Tabs](https://github.com/crftwr/xefm/blob/v1.10.0/doc/FOLDER_TABS_FEATURE.md)**, **[Quick View](https://github.com/crftwr/xefm/blob/v1.10.0/doc/QUICK_VIEW_FEATURE.md)** & **[Command Palette](https://github.com/crftwr/xefm/blob/v1.10.0/doc/COMMAND_PALETTE_FEATURE.md)** - Several places per pane, a live preview in the other pane, and every action by name
- **[Searching the OS Index](https://github.com/crftwr/xefm/blob/v1.10.0/doc/OS_INDEX_SEARCH_FEATURE.md)** & **[File Lists](https://github.com/crftwr/xefm/blob/v1.10.0/doc/FILE_LIST_IMPORT_FEATURE.md)** - Spotlight / Windows Search results, or any tool's list of paths, as a pane
- **[Find Similar Files](https://github.com/crftwr/xefm/blob/v1.10.0/doc/FIND_SIMILAR_FILES_FEATURE.md)** - Identical files and similar images, videos and audio
- **[Extension Packages](https://github.com/crftwr/xefm/blob/v1.10.0/doc/EXTENSIONS_FEATURE.md)** - Install, upgrade and write extensions
- **[The XeFM Skill for AI Agents](https://github.com/crftwr/xefm/blob/v1.10.0/doc/AGENT_SKILL_FEATURE.md)** - Let an AI coding agent edit your configuration and write extensions

Every feature guide is listed at the end of the [User Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/XEFM_USER_GUIDE.md#feature-documentation).
Recipes and community extensions are collected on the **[XeFM wiki](https://github.com/crftwr/xefm/wiki)**.

### Developer Documentation
- **[Project Structure](https://github.com/crftwr/xefm/blob/v1.10.0/doc/dev/PROJECT_STRUCTURE.md)** - Repository layout and where things live
- **[Path Polymorphism System](https://github.com/crftwr/xefm/blob/v1.10.0/doc/dev/PATH_POLYMORPHISM_SYSTEM.md)** - Storage-agnostic architecture and extensibility
- **[Navigation System](https://github.com/crftwr/xefm/blob/v1.10.0/doc/dev/NAVIGATION_SYSTEM.md)** - Core navigation implementation
- **[External Programs](https://github.com/crftwr/xefm/blob/v1.10.0/doc/dev/EXTERNAL_PROGRAMS_SYSTEM.md)** - Program integration system

## Archive Virtual Directory Browsing

Press `Enter` on an archive file (`.zip`, `.tar`, `.tar.gz`, `.tgz`, `.tar.bz2`,
`.tar.xz`) to browse it as if it were a regular directory — no extraction
needed. Navigate nested directories, view files, search by name or content, and
copy files out with the normal copy key; `Backspace` leaves the archive. `P`
creates a new archive, `U` extracts one. See the
[Archive Feature Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/ARCHIVE_FEATURE.md).

## Built-in File Viewers

Press `V` (or `Enter`) to view the selected file. XeFM picks the right viewer
for the file type: syntax-highlighted text (20+ formats, line numbers, wrapping,
in-file search), images with zoom / pan (inline in iTerm2 / kitty / sixel
terminals and in desktop mode), and *rendered* views for Markdown, JSON, and
CSV/TSV (`M` toggles rendered / raw). All viewers work on local files, inside
archives, and on remote SFTP / S3 paths without extraction or download.

![Text viewer](https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/text-viewer.jpg)

| Markdown | JSON / JSONL | CSV / TSV |
|:---:|:---:|:---:|
| <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/markdown-viewer.jpg" width="280"> | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/json-viewer.jpg" width="280"> | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/csv-viewer.jpg" width="280"> |
| Rendered headings, lists, code, and links | Collapsible, syntax-colored tree (`.json`, `.jsonl`, `.ndjson`) | Column-aligned table grid (`.csv`, `.tsv`) |

![Image viewer](https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/image-viewer.jpg)

## Themes & Visual Effects

XeFM ships a dozen built-in themes. Press `T` to cycle to the next theme, or pick one from the **View → Theme** menu — your choice is remembered across restarts. Define your own in `~/.xefm/config.py` and they appear in the picker alongside the built-ins.

| | | |
|:---:|:---:|:---:|
| <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-dark.jpg" width="260"><br>**Dark+** | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-monokai.jpg" width="260"><br>**Monokai** | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-dracula.jpg" width="260"><br>**Dracula** |
| <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-nord.jpg" width="260"><br>**Nord** | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-solarized.jpg" width="260"><br>**Solarized** | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-gruvbox.jpg" width="260"><br>**Gruvbox Dark** |
| <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-light.jpg" width="260"><br>**Light+** | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-solarized-light.jpg" width="260"><br>**Solarized Light** | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-sci-fi.jpg" width="260"><br>**Sci-Fi** |
| <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-cyber.jpg" width="260"><br>**Cyber** | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-segment-lcd.jpg" width="260"><br>**Segment LCD** | <img src="https://raw.githubusercontent.com/crftwr/xefm/v1.10.0/doc/images/theme-shinagawa.jpg" width="260"><br>**Shinagawa** |

In desktop mode a theme can also carry **visual effects** the GPU renders behind
and over the interface: background animations (`starfield`, `rain`, `hologram`,
…), CRT / phosphor screen post-effects, text-reveal animations, and translucent
surfaces. Effects are pure theme data — a custom theme can mix and match them,
and terminal mode ignores them. See
[Color Schemes & Visual Effects](https://github.com/crftwr/xefm/blob/v1.10.0/doc/COLOR_SCHEMES_FEATURE.md).

## Sub-shell Mode

Press `Shift-X` to temporarily suspend XeFM and enter a shell whose environment
describes the current panes and selection (`XEFM_LEFT_DIR`, `XEFM_THIS_DIR`,
`XEFM_LEFT_SELECTED`, …); type `exit` to return to XeFM. The full variable list
is in the [User Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/XEFM_USER_GUIDE.md#sub-shell-mode).

## Command Line Options

These apply to the terminal install and to source checkouts (where every command
also works as `python3 -m xefm …`); the desktop packages take no arguments.

```bash
xefm                                    # terminal mode (the default)
xefm --left /path/a --right /path/b     # startup directories
xefm --backend gui                      # desktop window — development path only
```

The full flag set is `--backend {tui,curses,gui,macos,windows}`, `--left DIR`,
`--right DIR`, `--version`, and `--help`. Backend details are in the
[Desktop Mode Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/DESKTOP_MODE_GUIDE.md#choosing-the-backend).

## Configuration

XeFM is highly configurable through `~/.xefm/config.py` — themes and visual
effects, key bindings, external programs and file associations, favorite
directories, and behavior settings. Open it with **Tools → Edit Configuration…**
in the menu bar, or edit the file directly. See the
**[Configuration Feature Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/CONFIGURATION_FEATURE.md)**.

## Extensions

Extension packages add actions, event hooks, themes, sort orders, filters,
picture formats, locations or syntax highlighting without touching
`config.py`, and install, upgrade and uninstall as one unit:

```bash
xefm ext install github:crftwr/xefm-extensions/compute-hash
xefm ext list
```

In the desktop apps, use **Tools → Advanced → Install Extension…** instead.
The wiki's **[Extensions](https://github.com/crftwr/xefm/wiki/Extensions)**
page lists what is available — the official packages in
[crftwr/xefm-extensions](https://github.com/crftwr/xefm-extensions), from
hashes and line counts to presigned S3 links and a classic blue theme, and the
community's.
To write your own, see [Extension Packages](https://github.com/crftwr/xefm/blob/v1.10.0/doc/EXTENSIONS_FEATURE.md) — or
give an AI coding agent [the XeFM skill](https://github.com/crftwr/xefm/blob/v1.10.0/doc/AGENT_SKILL_FEATURE.md) and ask
it for the feature. The extension API is a Preview, so the format may still
change.

## Troubleshooting

- *"Windows protected your PC"* when launching the portable `XeFM.exe` — the zip is not code-signed; click **More info** → **Run anyway**, or [unblock the zip](https://github.com/crftwr/xefm/blob/v1.10.0/doc/DESKTOP_MODE_GUIDE.md#windows--the-portable-zip) before extracting. The [Microsoft Store](https://apps.microsoft.com/detail/9PK2X44W810V) install is signed and never shows this prompt
- *"XeFM cannot be opened because the developer cannot be verified"* on macOS — right-click `XeFM.app` in *Applications* and choose **Open**, then confirm once
- Install problems (`command not found`, `externally-managed-environment`, upgrade errors) — see [Installation troubleshooting](https://github.com/crftwr/xefm/blob/v1.10.0/doc/XEFM_USER_GUIDE.md#installation-troubleshooting)

More in the [User Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/XEFM_USER_GUIDE.md#troubleshooting) and the [Desktop Mode Guide](https://github.com/crftwr/xefm/blob/v1.10.0/doc/DESKTOP_MODE_GUIDE.md#troubleshooting).

## Contact & Support

- **GitHub Issues**: [Report bugs or request features](https://github.com/crftwr/xefm/issues)
- **GitHub Discussions**: [Ask questions and show what you have built](https://github.com/crftwr/xefm/discussions)
- **Wiki**: [Recipes and community extensions](https://github.com/crftwr/xefm/wiki)
- **Microsoft Store**: [XeFM on the Store](https://apps.microsoft.com/detail/9PK2X44W810V) — the Windows desktop app
- **PyPI**: [pypi.org/project/xefm](https://pypi.org/project/xefm/) — released versions (`pipx install xefm`)
- **Author's X (Twitter)**: [@crftwr](https://x.com/crftwr)

## License

MIT License - see [LICENSE](https://github.com/crftwr/xefm/blob/v1.10.0/LICENSE) file for details.
