hf-local-hub 0.1.0

Lightweight local Hugging Face Hub server and client

hf-local-hub

Lightweight local Hugging Face Hub server and client - run HF Hub entirely on your machine.

Table of Contents

• Features
• Quick Start
• Installation
• Documentation
• Examples
• Architecture
• Development
• Contributing
• License

Features

• Single Binary: Static Go binary (~53MB), no runtime dependencies
• Full API Compatibility: Emulates essential Hugging Face Hub API
• Zero Configuration: Works out of the box
• Python Integration: Seamless with huggingface_hub, transformers, diffusers
• Local Storage: All models and datasets stored on your filesystem
• Cross-Platform: Linux, macOS, Windows
• Docker Support: Multi-stage Docker image
• Comprehensive Testing: Unit and integration tests

Quick Start

1. Install

Go Binary:

# Clone repository
git clone https://github.com/lyani/hf-local-hub.git
cd hf-local-hub

# Build server
make server

Python Package:

# Clone and install
git clone https://github.com/lyani/hf-local-hub.git
cd hf-local-hub/python
pip install -e .

Docker:

# Pull or build
docker build -t hf-local .
docker run -p 8080:8080 -v $(pwd)/data:/app/data hf-local

2. Start Server

# Using Go binary
./hf-local

# Using Python CLI
hf-local serve --port 8080

3. Use with Hugging Face Libraries

# Set endpoint
export HF_ENDPOINT=http://localhost:8080

# Download models
huggingface-cli download user/my-model

# Or use in Python
python -c "
from transformers import AutoModel
model = AutoModel.from_pretrained('user/my-model')
"

Installation

Requirements

• Go: 1.25+ (for building server)
• Python: 3.11+ (for Python client)
• Disk Space: ~100MB minimum (varies by model size)

Build from Source

# Clone repository
git clone https://github.com/lyani/hf-local-hub.git
cd hf-local-hub

# Build Go server
make server

# Install Python package
cd python
pip install -e ".[dev]"

Install via pip (Future)

pip install hf-local

Documentation

• Usage Guide - Complete usage instructions
• API Reference - REST API and Python client API
• Examples - Code examples
• Contributing - Development guidelines
• Security - Security policy and reporting

Examples

See docs/examples/ directory for complete examples:

• basic_upload.py - Upload model to local server
• transformers_demo.py - Use with Transformers
• diffusers_demo.py - Use with Diffusers
• api_client_demo.py - Custom API client

Architecture

┌─────────────────┐
│   Client Apps   │  (Transformers, Diffusers, etc.)
└────────┬────────┘
         │ HF_ENDPOINT=http://localhost:8080
         ▼
┌─────────────────┐
│  Go Server      │  (Gin + SQLite)
│  - API Layer    │
│  - File Serving │
│  - Auth (opt)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Local FS       │  (data/storage/models/...)
└─────────────────┘

Development

Setup

# Clone repository
git clone https://github.com/lyani/hf-local-hub.git
cd hf-local-hub

# Install Python dependencies
cd python
pip install -e ".[dev]"

Run Tests

# All tests
make test

# Go tests only
make server-test

# Python tests only
make python-test

Linting

# All linters
make lint

# Go lint
make server-lint

# Python lint
make python-lint

Docker

# Build image
make docker-build

# Run container
make docker-run

# Stop container
make docker-down

Development Workflow

1. Create feature branch: git checkout -b feat/your-feature
2. Make changes and commit with conventional commits
3. Run tests and linting: make test lint
4. Push and create pull request

Contributing

• Phase 0: Project Initialization
• Phase 1: Go Server Core
• Phase 2: Python Package & CLI
• Phase 3: Full HF Compatibility
• Phase 4: Packaging & Documentation
• Phase 5: CI/CD & GitHub Readiness

License

MIT License - see LICENSE file

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Project Status

• Phase 0: Project Initialization
• Phase 1: Go Server Core
• Phase 2: Python Package & CLI
• Phase 3: Full HF Compatibility
• Phase 4: Packaging & Documentation
• Phase 5: CI/CD & GitHub Readiness

Current Release

Version 0.1.0 - March 1, 2026

Installation

# From PyPI (after v0.1.0 release)
pip install hf-local

# Or install from source
git clone https://github.com/Akicou/hf-local-hub.git
cd hf-local-hub
make server
cd python && pip install -e .

Quick Start

# Start server
hf-local serve --port 8080

# Set HF_ENDPOINT
export HF_ENDPOINT=http://localhost:8080

# Use with huggingface_hub
python -c "
from huggingface_hub import snapshot_download
snapshot_download('user/my-model')
"

What's Included

• ✅ Go server with REST API (single binary)
• ✅ Python CLI and library
• ✅ Full Hugging Face Hub compatibility
• ✅ Upload/download workflows
• ✅ Transformers and Diffusers integration
• ✅ Docker support
• ✅ Comprehensive tests
• ✅ Complete documentation

Documentation

• Usage Guide - Complete usage instructions
• API Reference - REST API and Python client
• Examples - 4 working code examples
• Contributing - Development guidelines
• Security - Security policy

Source & Releases

• GitHub: https://github.com/Akicou/hf-local-hub
• PyPI: https://pypi.org/project/hf-local/
• Docker Hub: Coming soon

Support

• Issues: https://github.com/Akicou/hf-local-hub/issues
• Discussions: https://github.com/Akicou/hf-local-hub/discussions

Acknowledgments

Built with:

• Gin - Go web framework
• GORM - ORM for Go
• huggingface_hub - Python client
• Typer - CLI framework

Roadmap

v0.2.0

• Authentication and authorization
• User management
• Repository access control
• Git operations (branches, tags)
• Model metadata search

v0.3.0

• Web UI for repository management
• Model card editor
• File preview
• Model sharing features
• Integration with CI/CD

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: SECURITY.md

Star History