hf-model-tool 0.2.2

A CLI tool to manage Hugging Face models.

HF-MODEL-TOOL

A CLI tool for managing your locally downloaded Huggingface models and datasets

Disclaimer: This tool is not affiliated with or endorsed by Hugging Face. It is an independent, community-developed utility.

Screenshots

Welcome Screen

List All Assets

Features

Core Functionality

• Smart Asset Detection: Detect HuggingFace models, datasets, LoRA adapters, fine-tuned models, and custom formats
• Asset Listing: View all your AI assets with size information and metadata
• Duplicate Detection: Find and clean duplicate downloads to save disk space
• Asset Details: View model configurations and dataset documentation with rich formatting
• Directory Management: Add and manage custom directories containing your AI assets

Supported Asset Types

• HuggingFace Models & Datasets: Standard cached downloads from Hugging Face Hub
• LoRA Adapters: Fine-tuned adapters from training frameworks like Unsloth
• Custom Models: Fine-tuned models, merged models, and other custom formats

Installation

From PyPI (Recommended)

pip install hf-model-tool

From Source

git clone https://github.com/Chen-zexi/hf-model-tool.git
cd hf-model-tool
pip install -e .

Usage

Interactive Mode

hf-model-tool

Launches the interactive CLI with:

• System status showing assets across all configured directories
• Asset management tools for all supported formats
• Easy directory configuration and management

Programmatic API Usage

The tool can be imported as a Python library for integration with other tools like VLLM:

from hf_model_tool import get_downloaded_models, get_model_info

# Get all downloaded models in VLLM-compatible format
models = get_downloaded_models()
print(models)
# Output: ['bert-base-uncased', 'microsoft/Florence-2-large', 'facebook/bart-large-cnn', ...]

# Get detailed information about a specific model
info = get_model_info('microsoft/Florence-2-large')
print(info['path'])  # /home/user/.cache/huggingface/hub/models--microsoft--Florence-2-large
print(info['size'])  # Size in bytes
print(info['metadata'])  # Model configuration details

# Filter models by type
models = get_downloaded_models(
    include_custom_models=True,  # Include custom/merged models
    include_lora_adapters=False,  # Exclude LoRA adapters
    deduplicate=True  # Remove duplicates (default)
)

# Use with VLLM
from vllm import LLM
llm = LLM(model=models[0])  # Use any model name from the list

API Functions

• get_downloaded_models(): Returns a list of all downloaded models in VLLM-compatible naming format (e.g., "Qwen/Qwen3-30B-Instruct")

  • include_custom_models (bool): Include custom/merged models from non-HF directories (default: True)
  • include_lora_adapters (bool): Include LoRA adapters in results (default: False)
  • deduplicate (bool): Remove duplicate model names (default: True)

• get_model_info(model_name): Get detailed information about a specific model

  • Returns a dictionary with: path, size, type, subtype, metadata, source_directory, last_modified
  • Returns None if model not found

Command Line Usage

The tool provides comprehensive command-line options for direct operations:

Basic Commands

# Launch interactive mode
hf-model-tool

# List all detected assets
hf-model-tool -l
hf-model-tool --list

# Enter asset management mode
hf-model-tool -m
hf-model-tool --manage

# View detailed asset information
hf-model-tool -v
hf-model-tool --view
hf-model-tool --details

# Show version
hf-model-tool --version

# Show help
hf-model-tool -h
hf-model-tool --help

Directory Management

# Add a directory containing LoRA adapters
hf-model-tool -path ~/my-lora-models
hf-model-tool --add-path ~/my-lora-models

# Add a custom model directory
hf-model-tool -path /data/custom-models

# Add current working directory
hf-model-tool -path .

# Add with absolute path
hf-model-tool -path /home/user/ai-projects/models

Sorting Options

# List assets sorted by size (default)
hf-model-tool -l --sort size

# List assets sorted by name
hf-model-tool -l --sort name

# List assets sorted by date
hf-model-tool -l --sort date

Interactive Navigation

• ↑/↓ arrows: Navigate menu options
• Enter: Select current option
• Back: Select to return to previous menu
• Config: Select to access settings and directory management
• Main Menu: Select to return to main menu from anywhere
• Exit: Select to clean application shutdown
• Ctrl+C: Force exit

Key Workflows

1. Directory Setup: Add directories containing your AI assets (HuggingFace cache, LoRA adapters, custom models)
2. List Assets: View all detected assets with size information across all directories
3. Manage Assets: Delete unwanted files and deduplicate identical assets
4. View Details: Inspect model configurations and dataset documentation
5. Configuration: Manage directories, change sorting preferences, and access help

Configuration

Directory Management

Add custom directories containing your AI assets:

• HuggingFace Cache: Standard HF cache with models--publisher--name structure
• Custom Directory: LoRA adapters, fine-tuned models, or other custom formats
• Auto-detect: Let the tool automatically determine the directory type

Interactive Configuration

Access via "Config" from any screen:

• Directory Management: Add, remove, and test directories
• Sort Options: Size (default), Date, or Name
• Help System: Navigation and usage guide

Project Structure

hf_model_tool/
├── __main__.py       # Application entry point with welcome screen
├── cache.py          # Multi-directory asset scanning
├── ui.py             # Rich terminal interface components
├── utils.py          # Asset grouping and duplicate detection
├── navigation.py     # Menu navigation
├── config.py         # Configuration and directory management
└── asset_detector.py # Asset detection (LoRA, custom models, etc.)

Development

Requirements

• Python ≥ 3.7
• Dependencies: rich, inquirer, html2text

Logging

Application logs are written to ~/.hf-model-tool.log for debugging and monitoring.

Configuration Storage

Settings and directory configurations are stored in ~/.config/hf-model-tool/config.json

Contributing

We welcome contributions from the community! Please feel free to:

1. Open an issue at GitHub Issues
2. Submit a pull request with your improvements
3. Share feedback about your experience using the tool

License

This project is licensed under the MIT License - see the LICENSE file for details.