Installation

Quick Install

The fastest way to install F2 Commander:

Using pipx (Recommended)

# Install F2 Commander
pipx install f2-commander

# Run it
f2

Using uvx

# One-time run (no installation needed)
uvx --from f2-commander f2

Method 1: pipx (Recommended)

pipx installs Python applications in isolated environments, keeping your system clean.

1. Install pipx

On macOS:

brew install pipx
pipx ensurepath

On Linux (Debian/Ubuntu):

sudo apt update
sudo apt install pipx
pipx ensurepath

On Linux (Fedora):

sudo dnf install pipx
pipx ensurepath

On Linux (Arch):

sudo pacman -S python-pipx
pipx ensurepath

Or with pip (any platform):

python3 -m pip install --user pipx
python3 -m pipx ensurepath

2. Install F2 Commander

pipx install f2-commander

3. Run F2 Commander

f2

After installation, restart your terminal or run source ~/.bashrc (or ~/.zshrc) to update your PATH.

Method 2: uvx

uv is a fast Python package installer and runner. You can use it to run F2 Commander without installing it permanently.

1. Install uv

# On macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip:
pip install uv

2. Run F2 Commander

# Run without installing:
uvx --from f2-commander f2

# This downloads and runs the latest version each time

Tip: With uvx, you always get the latest version without needing to update manually!

Method 3: From Source

For developers or if you want to run the latest development version:

1. Clone the repository

git clone https://github.com/candidtim/f2-commander.git
cd f2-commander

2. Option A: Install with pipx

# Build the package
uv build

# Install with pipx
pipx install --force dist/f2_commander-*.tar.gz

2. Option B: Run directly with uv

# Run without installing
uv run f2

Optional Dependencies

F2 Commander core functionality works out of the box. However, some features require additional packages:

For Remote File Systems

Different protocols require different fsspec implementation packages. Install them as needed:

Note: This list is non-exhaustive. See fsspec documentation for more protocols.

The connection dialog in F2 Commander (Ctrl+T) shows which package is needed for each protocol.

For Archive Support

libarchive should be available on most systems. If not:

macOS:

brew install libarchive

Linux (Debian/Ubuntu):

sudo apt-get install libarchive13

Linux (Fedora/RHEL):

sudo dnf install libarchive

Linux (Arch):

sudo pacman -S libarchive

Post-Installation

First Run

Simply run:

f2

Getting Started

• Press ? to see the built-in help
• Press Ctrl+P to open the Command Palette and explore available actions
• Press Ctrl+, to open the Configuration dialog
• Press q to quit

Configuration

F2 Commander creates a configuration file on first run. The location is platform-specific:

• Linux: ~/.config/f2commander/config.json
• macOS: ~/Library/Application Support/f2commander/config.json

Updating F2 Commander

With pipx:

pipx upgrade f2-commander

With uvx:

No update needed! uvx always runs the latest version.

From source:

cd f2-commander
git pull
uv build
pipx install --force dist/f2_commander-*.tar.gz

Uninstalling F2 Commander

With pipx:

pipx uninstall f2-commander

Optionally, remove the configuration directory:

# Linux
rm -rf ~/.config/f2commander

# macOS
rm -rf ~/Library/Application\ Support/f2commander

Troubleshooting

Command not found: f2

If you get "command not found" after installation:

1. Restart your terminal
2. Or run: source ~/.bashrc (or ~/.zshrc)
3. Ensure pipx's bin directory is in your PATH (run pipx ensurepath)

Python version issues

F2 Commander requires Python 3.10 or later. Check your version:

python3 --version

If your Python version is too old, you'll need to install a newer version from python.org or your package manager.

Terminal compatibility

F2 Commander works in most terminal emulators. For best experience:

• Use a modern terminal with Unicode support
• For image preview: Use terminals with TGP or Sixel support (iTerm2, Ghostty, Kitty, etc.)
• Ensure your terminal size is at least 88x24 characters

Permission issues

If you encounter permission errors:

• Don't use sudo with pipx or uvx
• Install to user directory (pipx does this by default)
• Ensure you have write permissions to the configuration directory

Archive support not working

If you can't open archives, install libarchive:

# macOS
brew install libarchive

# Linux (Debian/Ubuntu)
sudo apt-get install libarchive13

Still having issues?

Report issues on GitHub Issues with:

• Your operating system and version
• Python version (python3 --version)
• Installation method used
• Error message or description of the problem