Still needs network connection after model file having downloaded into cache on local device?

[jealthterry-hub]

My OS is Ubuntu22.0.4. I have no problems in running project.
Now I wanna make this project available offline, meaning that it still works in the case of no network connection.
I know that once project has run, model files(.pth file) are automatically downloaded on local, and the project uses those cache files repeatedly,
But even so, I have to keep network on, otherwise it reports the following error:

Max retries exceeded with url: /hexgrad/Kokoro-82M/resolve/main/config.json (Caused by NameResolutionError("<urllib3.connection.HTTPSConnection object at 0x7e56d091aaa0>: Failed to resolve 'huggingface.co' ([Errno -3] Temporary failure in name resolution)"))'), '(Request ID: 50e3b537-1b49-437b-9300-bdbbae90cc03)')' thrown while requesting HEAD https://huggingface.co/hexgrad/Kokoro-82M/resolve/main/config.json
Retrying in 1s [Retry 1/5].

Is there any way to handle it @PierrunoYT @6Morpheus6 ?

[6Morpheus6]

Hi @jealthterry-hub
I haven't written the app, and I can't see the whole traceback of your error.
But looking at the code I think the problem might be in models.py
Can you edit models.py at line 421 and line 438 and set force_download=False please?
Let me know if this fixes your problem. I haven't installed Kokoro right now. But I can look into it if it doesn't work.

[PierrunoYT]

Solution: Offline Mode Implementation

Hi @jealthterry-hub,

Thank you for reporting this issue! I've implemented offline mode support that allows the application to run completely without internet connection after the initial setup.

The Problem

The application was attempting to connect to HuggingFace to verify/download files even when they were already cached locally, causing the error:

Max retries exceeded with url: /hexgrad/Kokoro-82M/resolve/main/config.json
(Caused by NameResolutionError: Failed to resolve 'huggingface.co')

The Solution

I've modified the code to support standard HuggingFace offline mode environment variables. Now you can enable offline mode and the application will only use locally cached files.

How to Use on Ubuntu 22.04

Step 1: Initial Setup (requires internet, one-time only)

# Run once to download all required files
python tts_demo.py

Step 2: Enable Offline Mode

# Set the environment variable
export HF_HUB_OFFLINE=1

# Run the application
python tts_demo.py
# or
python gradio_interface.py

Step 3: Make it Permanent (optional)

# Add to your .bashrc to enable offline mode by default
echo 'export HF_HUB_OFFLINE=1' >> ~/.bashrc
source ~/.bashrc

What Changed

Code Changes in models.py:

1. Added detection for HF_HUB_OFFLINE and TRANSFORMERS_OFFLINE environment variables
2. Modified all HuggingFace Hub download calls to use local_files_only=True when offline mode is enabled
3. Added validation to ensure required files exist before attempting to use them
4. Improved error messages to clearly indicate when files are missing in offline mode

Updated README.md:

• Added offline mode to features list
• Added quick start section for offline mode
• Added troubleshooting entry for network connection issues

Verification

When offline mode is enabled, you should see this message in the console:

INFO - Running in OFFLINE mode - will only use locally cached files

Required Files

For offline mode to work, these files must exist (they're downloaded on first run):

• kokoro-v1_0.pth (~330 MB) - Main model file
• config.json (~1 KB) - Configuration file
• voices/*.pt (at least one) - Voice model files

Troubleshooting

If you get "No voice files found locally":

# Temporarily disable offline mode and re-download
unset HF_HUB_OFFLINE
python tts_demo.py
# Then re-enable offline mode
export HF_HUB_OFFLINE=1

If you get "Model file not found":

# Check if the file exists
ls -lh kokoro-v1_0.pth config.json
ls -lh voices/*.pt

# If missing, download with internet connection
unset HF_HUB_OFFLINE
python tts_demo.py

Benefits

✅ True offline operation - No network required after initial setup
✅ Standard compliance - Uses official HuggingFace environment variables
✅ Easy to use - Simple environment variable toggle
✅ Backward compatible - Default behavior unchanged
✅ Clear error messages - Know exactly what's missing and how to fix it

Technical Details

The implementation uses the local_files_only parameter in all hf_hub_download() calls, which prevents any network access when set to True. This is the standard way to enable offline mode in HuggingFace libraries.

The environment variables HF_HUB_OFFLINE and TRANSFORMERS_OFFLINE are the official HuggingFace methods for enabling offline mode, so this solution follows best practices.

---

Please test this solution and let me know if it resolves your issue! The application should now work perfectly on your Ubuntu 22.04 system without any network connection once the files are downloaded.

[jealthterry-hub]

Great work!!!
working well now.