hf-to-ollama is a utility tool that lets you seamlessly download Hugging Face GGUF files via an interactive step-by-step selection process, and immediately create them as Ollama models.

It also offers easy management of your installed models, including parameter modification and deletion.

✨ Features

• 📥 Intuitive Installation (Install) Supports selecting GGUF and ADAPTER files, configuring parameters, auto-downloading, and creating models seamlessly.

• 🔍 Real-time Model Search Type a model name or keyword and the tool will search the Hugging Face Hub for GGUF-compatible models in real-time. Browse results sorted by popularity and select with arrow keys.

• 📁 Virtual Directory Navigation Browse hundreds of model files in a clean, hierarchical directory structure right in your terminal.

• ⚙️ Simple Management (Config) Provides features to inspect the generated Modelfile, quickly regenerate models with updated parameters, and delete installed models with a single click.

• 🤖 Script-friendly Non-interactive Mode Run installs from CI or shell scripts with --repo, --file, --adapter, --name, --dir, --non-interactive, and --yes.

• 🔁 Resumable and Locked Downloads Interrupted GGUF downloads can resume from a valid .part file, and per-file lock files prevent two processes from writing the same target at once.

• 🛡️ Built-in Security Includes multi-layered security defenses: path traversal prevention, model name injection blocking, GGUF magic signature verification, managed manifest boundaries, Ollama executable override validation, HF token masking in error logs, and more.

🆕 What's New in v1.2.0

• Fully wired non-interactive installs for remote Hugging Face repositories and local GGUF folders.
• Safer local-model handling: absolute local GGUF paths, managed manifest boundaries, local adapter updates, and symlink filtering.
• Resumable downloads with .part metadata, HTTP Range support, content-range validation, and per-target lock files.
• Hardened Ollama executable resolution with OLLAMA_BIN / OLLAMA_PATH overrides and executable validation.
• Package metadata updates: Node.js >=22.13.0, npm package manager pinning, CLI version synced from package.json, and automated regression tests.

📋 Prerequisites

Before using this tool, make sure you have the following installed:

• Node.js (Version 22.13.0 or higher)
• Ollama (Must be pre-installed and running as a background service)
• (Optional) Hugging Face Access Token (Required for private or gated models. Supply it via the HF_TOKEN environment variable or --token option)

📦 Installation

To build and run in your local environment:

npm install
npm run build

To install globally via NPM:

npm install -g hf-to-ollama

💻 Usage Guide

1️⃣ Interactive Install

Execute the installation command and follow the terminal prompts to easily install your models step-by-step.

hf-to-ollama install

📌 Process:

1. Choose Input Mode: Select either Enter Repository ID directly (e.g., username/repo) or Search models by name.
   • (If Search is selected): Simply type a keyword, and the tool will fetch and display the most popular models featuring GGUF formats directly from the Hugging Face Hub in real-time. Use arrow keys to select your model.
2. Select the main GGUF file from the list
3. Confirm and select an ADAPTER (e.g., LoRA) file if needed
4. Set hardware generation parameters (temperature, top_p, top_k, num_ctx)
5. Specify your local save directory
6. Watch the download progress, followed by automatic Modelfile generation and ollama create
   • ⚡ Smart Download: Redundant downloads are skipped, interrupted downloads can resume, and a lock file prevents duplicate writers.

2️⃣ Configuration

Manage your locally installed Ollama models via hf-to-ollama config.

hf-to-ollama config

• View the list of currently installed Ollama models
• Inspect the internal structure of each model's Modelfile (View)
• Change or Remove ADAPTERs, update generation parameters and seamlessly recreate the model (Edit)
• Remove unused models and wipe local data (Delete)

3️⃣ Non-interactive Install (for Scripts)

Declare all parameters in a single command, skipping any user prompts entirely. Very useful when creating automated pipelines. Use a Hugging Face repo ID for remote installs or a local folder path for local GGUF imports.

📢 Security Notice: Do not expose sensitive or hardcoded repository details in public scripts. Use variables or placeholder names according to your environment.

hf-to-ollama install \
  --repo <hf_repo_path> \
  --file <model_gguf.gguf> \
  --adapter <adapter_gguf.gguf> \
  --parameter temperature=1.0 \
  --parameter top_p=0.95 \
  --parameter top_k=64 \
  --parameter num_ctx=32768 \
  --dir <local_save_directory> \
  --name <ollama_model_name_to_create> \
  --non-interactive \
  --yes

💡 Append --token <your_access_token> to the command if you're trying to download gated models.

🛡️ Security Features

hf-to-ollama is distributed as a public npm package and includes multi-layered security defenses against potential abuse:

| Defense | Description | |---|---| | Path Traversal Prevention | Validates that downloaded files cannot escape the designated save directory. | | Model Name Validation | Blocks shell metacharacters, path separators, and other dangerous characters in model names. | | Modelfile Injection Prevention | Blocks newline injection in parameter values to prevent malicious directive insertion. | | Disk Exhaustion Protection | Immediately terminates streams exceeding 150GB to prevent disk space exhaustion attacks. | | GGUF Magic Signature Check | Verifies the first 4 bytes of downloaded files to detect disguised malicious executables. | | Symlink Filtering | Ignores symbolic links during local directory scanning to prevent system file leakage. | | Managed Manifest Boundary | Ignores or rejects install records that point outside the managed ~/.hf-to-ollama root. | | Download Lock & Resume Metadata | Uses per-target lock files and .part.json metadata before resuming interrupted downloads. | | Ollama Executable Validation | Supports OLLAMA_BIN / OLLAMA_PATH overrides and validates candidates with --version before use. | | HF Token Masking | Automatically redacts authentication tokens from error messages and stack traces. | | API Rate Limiting | Applies 300ms debounce to real-time searches to prevent HF server overload. | | Loop Prevention | Force-terminates the process after 5 consecutive invalid inputs. | | Temp File Permissions | Sets owner-only permissions (0o600) on in-progress .part download files. |

📝 Generated Modelfile Example

Based on your settings, the background engine writes a Modelfile similar to the one below, which is then fed into ollama create:

FROM ./your-model.gguf
ADAPTER ./your-adapter.gguf
PARAMETER temperature 1.0
PARAMETER top_p 0.95
PARAMETER top_k 64
PARAMETER num_ctx 32768

💬 Issues & Feedback

If you encounter any bugs or have feature requests, please open an issue on GitHub:

👉 https://github.com/Aminoragit/hf-to-ollama/issues