Downloading models from China: ModelScope and HF mirrors

Who this is for and what you will be able to do

This is for readers who have started running open models locally and find model downloads from abroad slow or failing. After working through it, you will pick a download method that suits your network, fetch a model to a local folder with a few lines of Python or a shell command, and switch pip and conda to Chinese mirrors so later installs are faster.

The five download methods

The "General Setting" chapter of Datawhale's open-source self-llm course lists five methods: Hugging Face's official command-line tool huggingface-cli, a Hugging Face mirror, ModelScope, git-lfs and OpenXLab^[1]. They differ in where the files come from. The first two pull from Hugging Face's repositories, one directly and one through a mirror. ModelScope and OpenXLab are model platforms hosted in China. git-lfs clones the model repository with git.

Preparation

Install the Hugging Face command-line tool first:

pip install -U huggingface_hub

The guide uses the huggingface-cli tool, which comes with the huggingface_hub package^[1]. The ModelScope method also needs modelscope and transformers, and OpenXLab needs openxlab. All are installed with pip.

Method 1: download with huggingface-cli

Save the script below as a Python file and run it. The guide uses internlm/internlm-chat-7b as the model name, and your_path must be replaced with your own local directory:

import os

# 下载模型
os.system('huggingface-cli download --resume-download internlm/internlm-chat-7b --local-dir your_path')

Two options matter here. --resume-download resumes an interrupted download instead of starting over. --local-dir sets the local storage path, which must be an absolute path on Linux^[1].

Method 2: download through the Hugging Face mirror

The mirror method is the same, except that the script sets the environment variable HF_ENDPOINT to point at a mirror site before downloading:

import os

# 设置环境变量
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

# 下载模型
os.system('huggingface-cli download --resume-download internlm/internlm-chat-7b --local-dir your_path')

The guide suggests the HF Mirror site (hf-mirror.com) for more on using the mirror^[1].

Method 3: download with ModelScope

ModelScope uses the snapshot_download function from the modelscope package. The first argument is the model name, and the cache_dir argument sets where the files go. The guide advises an absolute path for cache_dir^[1]. Example:

import torch
from modelscope import snapshot_download, AutoModel, AutoTokenizer
import os
model_dir = snapshot_download('Shanghai_AI_Laboratory/internlm-chat-7b', cache_dir='your path', revision='master')

Before running it, install the packages with pip install modelscope and pip install transformers^[1]. This route does not depend on Hugging Face's domain, so it is usually the most direct option for users in China.

Method 4: clone with git-lfs

To use git-lfs, download the installer from the git-lfs website and install it, then run git lfs install in a terminal. After that you can clone model repositories. The guide's example is:

git clone https://huggingface.co/internlm/internlm-7b

The guide also says this route needs "a bit of Magic", meaning some way to reach overseas sites^[1]. If your network cannot do that, use one of the methods above.

Method 5: download with OpenXLab

OpenXLab can download weight files directly once you give it the model repository address, the model name and the output location^[1]. Install the client, then call download:

pip install -U openxlab

from openxlab.model import download
download(model_repo='OpenLMLab/InternLM-7b', model_name='InternLM-7b', output='your local path')

Switching pip to a mirror

Package installs are often slow too. The guide recommends the MirrorZ mirror at mirrors.cernet.edu.cn for pip^[2].

To use the mirror for a single install, add the -i option:

pip install -i https://mirrors.cernet.edu.cn/pypi/web/simple some-package

To make it the default, upgrade pip to version 10.0.0 or later, then run the configuration command^[2]:

python -m pip install --upgrade pip
pip config set global.index-url https://mirrors.cernet.edu.cn/pypi/web/simple

If pip's default source is so slow that upgrading pip is hard, the guide suggests upgrading through the mirror: python -m pip install -i https://mirrors.cernet.edu.cn/pypi/web/simple --upgrade pip^[2].

Switching conda to a mirror

The mirror provides the Anaconda repository and third-party channels such as conda-forge, msys2 and pytorch. Setup means editing the .condarc file in your home directory. On Linux and macOS it is ${HOME}/.condarc; on Windows it is C:\Users\<YourUserName>\.condarc^[2].

On Windows you cannot create a file named .condarc directly. The guide says to run conda config --set show_channel_urls yes first to generate it, then edit it^[2].

The guide also gives a one-command quick configuration that writes Tsinghua TUNA mirror addresses:

cat <<'EOF' > ~/.condarc
channels:
  - defaults
show_channel_urls: true
default_channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2
custom_channels:
  conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
EOF

This overwrites an existing ~/.condarc, so back up your own configuration first.

Common questions

What if a download stops halfway? Run the same command again with --resume-download, and the completed parts are kept^[1].

**Can --local-dir be a relative path?** The guide requires an absolute path on Linux, so an absolute path is the safe choice^[1].

pip is still slow after switching? Check that the configuration took effect, or pass -i to name the mirror for one install^[2].

Limits

Mirrors are third-party services, and their addresses, sync speed and coverage can change. The examples in the guide use the model name internlm-chat-7b; check the model page for the current name you want. The same model on ModelScope and on Hugging Face may not have identical file layouts or configuration, so if loading fails, compare against the repository you actually downloaded.

Next steps

After the download, load and run the model with the Hugging Face Transformers or ModelScope documentation. For serving a model, see this site's practice articles on vLLM and Ollama.

Adapted from the "Model download" and "pip and conda mirror" lessons of Datawhale's open-source self-llm project^[1][2], released under the Apache-2.0 License.