modelscope-hub 0.2.0

Why modelscope-hub?

modelscope-hub connects your code to the ModelScope ecosystem — models, datasets, Studio spaces, skills, and MCP servers — through a single HubApi class or the ms-hub CLI.

• Unified repo interface — one set of methods for models, datasets, studios, skills, and MCP servers
• OpenAPI-first — built on the ModelScope OpenAPI surface with transparent legacy fallback
• Production-grade downloads — HTTP Range resume, parallel range download for large files, per-file retry with backoff, SHA256 integrity checks, file lock for multiprocess safety, offline mode, progress callbacks, and intra-cloud acceleration
• Full lifecycle CLI — download, upload, deploy, manage secrets, inspect cache — all from the terminal
• Deep ecosystem integration — seamless access to 100K+ models and datasets on ModelScope Hub; works with the modelscope training framework, Studio deployment platform, and MCP server infrastructure

News

v0.2.0 (2026-08-01)

• Breaking: HubApi.login() now raises NetworkError / ServerError / RequestTimeoutError for non-authentication failures instead of always raising AuthenticationError — widen except AuthenticationError to HubError if you catch any login failure
• Fix: network, timeout and 5xx errors during login are no longer misreported as an invalid token; a failed login no longer deletes stored credentials; bare and upper-case endpoints are accepted (e.g. --endpoint modelscope.ai)
• Enhancement: a rejected login probes the peer ModelScope site and suggests --endpoint when the token is valid there; --verbose prints the full error cause chain

v0.1.9 (2026-07-31)

• Fix: two stale unit tests that failed in downstream distro sandboxes (#46, NixOS): align the mcp deploy call-shape assertion and the parse_timestamp timezone-normalization contract
• Feature: ms-hub mcp deploy prints the operational URL after deployment; new --auth-check and repeatable --env KEY=VALUE options; --transport-type now validates against sse/streamable_http
• CI: new citest workflow — mock-mode test suite (no credentials/network, mirrors distro build sandboxes) on Python 3.10/3.12/3.14 plus ruff/mypy hard gates; releases now require a green test gate before publishing; added a pre-commit config
• Quality: ruff & mypy debt cleared to zero; lint/type-check targets aligned to the supported Python floor (3.10)

v0.1.8 (2026-07-21)

• Feature: ms-hub agent raw file transfer (download/upload/list) for remote agent repos; visibility support for agent hub; cache checksum verification (ms-hub cache verify)
• Fix: forward progress_callbacks through HubApi.download_repo so custom download-progress callbacks work end-to-end; harden legacy (pre-1.38) cache auto-detection (reuse existing {cache}/models/... and default {cache}/hub/models/... layouts); normal (non-LFS) file upload
• Packaging: rename console scripts to modelscope-hub / ms-hub to avoid a file conflict with the modelscope package (e.g. FreeBSD pkg)

Installation

pip install modelscope-hub

Requires Python 3.10+. Lightweight — only requests, tqdm, filelock, urllib3.

Quick Start

Authenticate

ms-hub login
# or pass a token directly
ms-hub login --token $MODELSCOPE_API_TOKEN

Get your token at modelscope.cn/my/access/token or modelscope.ai/my/access/token.

from modelscope_hub import HubApi

api = HubApi(token="your-token")
user = api.whoami()
print(user.username)

Download

# Full snapshot
ms-hub download Qwen/Qwen3-0.6B

# Single file
ms-hub download Qwen/Qwen3-0.6B config.json

# With filters
ms-hub download Qwen/Qwen3-0.6B --include "*.safetensors" --exclude "*.bin"

# Directly into a local directory (bypasses cache)
ms-hub download Qwen/Qwen3-0.6B --local-dir ./my-model

path = api.download_file("Qwen/Qwen3-0.6B", "model", "config.json")

snapshot = api.download_repo(
    "Qwen/Qwen3-0.6B", "model",
    allow_patterns=["*.safetensors", "*.json"],
    max_workers=8,
)

# Offline mode — return cached path without network access
path = api.download_file("Qwen/Qwen3-0.6B", "model", "config.json", local_files_only=True)

Upload

ms-hub upload my-org/my-model ./weights.safetensors
ms-hub upload my-org/my-model ./output --repo-type model --commit-message "add weights"

api.upload_file("my-org/my-model", "model", "./weights.safetensors", "weights.safetensors")
api.upload_folder("my-org/my-model", "model", "./output", path_in_repo="")

Create a Repository

ms-hub create my-org/my-model --repo-type model --visibility private

api.create_repo("my-org/my-model", "model", visibility="private", license="apache-2.0")

Deploy a Studio

ms-hub deploy my-org/chat-demo --repo-type studio
ms-hub logs my-org/chat-demo --log-type run
ms-hub stop my-org/chat-demo --repo-type studio

api.deploy_repo("my-org/chat-demo", "studio")
api.get_repo_logs("my-org/chat-demo", log_type="run")
api.stop_repo("my-org/chat-demo", "studio")

CLI Reference

The CLI is available as both ms-hub and modelscope-hub.

Global options (placed before or after the subcommand):

--token and --endpoint can be placed either before or after the subcommand: ms-hub --token xxx download ... and ms-hub download ... --token xxx are equivalent.

ms-hub login

Authenticate and persist your token locally.

ms-hub login                          # interactive prompt
ms-hub login --token $MY_TOKEN        # non-interactive

ms-hub whoami

Show the user associated with the current token.

ms-hub whoami
ms-hub whoami --token $MY_TOKEN   # check a specific token without logging in

ms-hub download

Download a single file or a full repository snapshot.

ms-hub download Qwen/Qwen3-0.6B                                  # full snapshot
ms-hub download Qwen/Qwen3-0.6B config.json                      # single file
ms-hub download Qwen/Qwen3-0.6B --include "*.safetensors"         # filter by glob
ms-hub download Qwen/Qwen3-0.6B --local-dir ./out --max-workers 8 # direct download
ms-hub download my-org/my-data --repo-type dataset --revision v2   # dataset at tag

# Download multiple specific files at once
ms-hub download Qwen/Qwen3-0.6B config.json tokenizer.json generation_config.json

# Download only safetensors, skip GGUF and bin weights
ms-hub download Qwen/Qwen3-0.6B --include "*.safetensors" --exclude "*.bin" "*.gguf"

# Download a dataset at a specific tag into a local directory
ms-hub download my-org/my-data --repo-type dataset --revision v2 --local-dir ./data

# Use a custom cache directory and 8 parallel threads
ms-hub download Qwen/Qwen3-0.6B --cache-dir /data/hub-cache --max-workers 8

# Force re-download even if already cached
ms-hub download Qwen/Qwen3-0.6B config.json --force

# Download all skills from a collection (legacy flag)
ms-hub download --collection my-org/skill-collection

# Enable parallel range download for large files (env var)
MODELSCOPE_DOWNLOAD_PARALLELS=4 ms-hub download Qwen/Qwen3-0.6B

# Use the modelscope.ai endpoint (global option, before subcommand)
ms-hub --endpoint https://modelscope.ai download Qwen/Qwen3-0.6B

ms-hub upload

Upload a file or folder to a repository.

ms-hub upload my-org/my-model ./weights.safetensors                       # single file
ms-hub upload my-org/my-model ./output models/ --repo-type model          # folder → subdir
ms-hub upload my-org/my-model . --include "*.py" --commit-message "code"  # filtered folder

# Upload a single file with a custom commit message
ms-hub upload my-org/my-model ./weights.safetensors --commit-message "add fp16 weights"

# Upload a folder into a subdirectory of the repo
ms-hub upload my-org/my-model ./output models/ --repo-type model

# Upload only Python files from the current directory
ms-hub upload my-org/my-model . --include "*.py" --commit-message "update code"

# Upload only safetensors, skip checkpoints
ms-hub upload my-org/my-model ./output --include "*.safetensors" --exclude "*.ckpt" "*.bin"

# Upload to a dataset repo on a specific branch
ms-hub upload my-org/my-data ./data --repo-type dataset --revision dev

# Upload with extended commit description
ms-hub upload my-org/my-model ./weights.safetensors \
  --commit-message "v2 weights" \
  --commit-description "Retrained with extended dataset, 3 epochs, lr=2e-5"

# Resumable upload: interrupted uploads resume automatically via cache
ms-hub upload my-org/my-model ./large-folder
# If interrupted, just re-run the same command — already uploaded files are skipped

# Disable upload cache (no resume, fresh upload every time)
ms-hub upload my-org/my-model ./output --no-cache

# Disable progress bars (useful for CI/CD pipelines)
ms-hub upload my-org/my-model ./output --disable-tqdm

ms-hub create / ms-hub info / ms-hub list / ms-hub delete

Repository management.

ms-hub create my-org/my-model --repo-type model --visibility private
ms-hub create my-org/demo --repo-type studio --sdk-type gradio
ms-hub info my-org/my-model --repo-type model
ms-hub list --repo-type model --owner my-org --page-size 20
ms-hub delete my-org/my-model --repo-type model --yes

Deprecation notice: delete_repo / ms-hub delete emits a DeprecationWarning — programmatic repo deletion is restricted for security reasons and will be restored once token-scoped auth is available. Use the web console to delete repos.

delete_files requires cookie-based session auth; API tokens may receive a 401 error.

ms-hub deploy / ms-hub stop / ms-hub logs / ms-hub settings

Manage Studio and MCP deployments.

ms-hub deploy my-org/chat-demo --repo-type studio
ms-hub logs my-org/chat-demo --log-type run --keyword ERROR --page-size 50
ms-hub settings my-org/chat-demo cpu=4 memory=8192
ms-hub stop my-org/chat-demo --repo-type studio

ms-hub secret

Manage secrets for Studio spaces (studio only, --repo-type defaults to studio).

ms-hub secret add my-org/demo API_KEY sk-xxx
ms-hub secret list my-org/demo
ms-hub secret update my-org/demo API_KEY sk-new
ms-hub secret delete my-org/demo API_KEY --yes

ms-hub mcp

Manage MCP (Model Context Protocol) servers.

ms-hub mcp list --search weather --page-size 10
ms-hub mcp info my-org/weather-mcp
ms-hub mcp deploy my-org/weather-mcp
ms-hub mcp undeploy my-org/weather-mcp

ms-hub cache

Inspect and clean the local download cache.

ms-hub cache scan
ms-hub cache scan --cache-dir /data/cache
ms-hub cache verify Qwen/Qwen3-0.6B
ms-hub cache verify Qwen/Qwen3-0.6B --local-dir ./Qwen3-0.6B
ms-hub cache clear --repo-type model --yes
ms-hub cache clear --repo-id my-org/old-model --repo-type model --yes

ms-hub agent

Low-level raw file transfer for remote agent repositories: download, upload, list. This command transfers files as-is, with no framework awareness.

ms-hub agent download -r user/my-agent --local-dir ./my-agent   # download raw files
ms-hub agent upload   -r user/my-agent --local-dir ./my-agent   # upload raw

Framework-aware operations (cross-framework convert, watch/bidirectional sync, status, backups, restore, stop) live in modelscope-agent — use ms-agent agent ... instead. For example, to download and convert in one step: ms-agent agent download -f qoder -r user/my-agent --target-framework qwenpaw.

ms-hub agent download -r user/my-agent
ms-hub agent download -r user/my-agent --local-dir ./my-agent --revision master

ms-hub agent upload -r user/my-agent --local-dir ./my-agent
ms-hub agent upload -r user/my-agent --local-dir ./my-agent --dry-run

SDK API Overview

All operations go through a single entry point:

from modelscope_hub import HubApi

# Connect to modelscope.cn (default)
api = HubApi(token="...")

# Or connect to modelscope.ai
api = HubApi(token="...", endpoint="https://modelscope.ai")

Ecosystem Integration

modelscope-hub is the hub connectivity layer for the ModelScope ecosystem:

┌────────────────────────────────────────────────┐
│              ModelScope Platform                │
│   modelscope.cn  ·  modelscope.ai              │
│                                                │
│  Models · Datasets · Studios · Skills · MCP    │
└───────────────────┬────────────────────────────┘
                    │  OpenAPI / Legacy API
                    ▼
            ┌───────────────┐
            │ modelscope-hub│  ← this library
            │  SDK  +  CLI  │
            └───┬───────┬───┘
                │       │
        ┌───────┘       └────────┐
        ▼                        ▼
  modelscope framework    your application
  (training · eval)       (inference · deploy)

• Browse & discover — search 100K+ models and datasets via list_repos / ms-hub repo list
• Download & cache — pull model weights, tokenizer configs, or entire datasets into a managed cache or a local directory; supports offline mode via local_files_only
• Train & fine-tune — use with the modelscope framework: train locally, then push results back
• Deploy — launch a Studio space or MCP server directly from the CLI or SDK
• Automate — integrate into CI/CD pipelines with environment-variable auth and --yes flags for non-interactive operation

Configuration

Run ms-hub list --envs to see all configurable environment variables with their current values.

Token is persisted locally after ms-hub login and auto-loaded in subsequent sessions.

Backward Compatibility

modelscope-hub provides a compatibility layer for code written against the old modelscope.hub API surface. The old SDK can delegate directly to modelscope_hub.compat:

from modelscope_hub.compat import snapshot_download, model_file_download
from modelscope_hub.compat import LegacyHubApi as HubApi

All legacy parameter names (allow_file_pattern, ignore_file_pattern, cookies, etc.) are accepted and mapped to the new implementation.

Development

git clone https://github.com/modelscope/modelscope_hub.git
cd modelscope_hub
make install    # pip install -e ".[dev]"
make test       # unit tests (no network)
make lint       # ruff check
make typecheck  # mypy

See make help for all available targets.

License

Apache 2.0 — see LICENSE.

Citation

@Misc{modelscope-hub,
  title = {modelscope-hub: The official Python client to connect with ModelScope Hub.},
  author = {The ModelScope Team},
  howpublished = {\url{https://github.com/modelscope/modelscope_hub}},
  year = {2026}
}