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.4.0 (2026-09-01)

• Feature: complete OpenAPI coverage for Agent-IDP, MCP, and Studios — Agent Ed25519 identities, OIDC discovery/JWKS and signed JWT issuance (HubApi, ms-hub agent-idp); Studio lists, variables and configuration options; hosted MCP discovery; protected visibility and runtime metadata; read-only tokens can log in and rejected writes name the required tier. Agent private JWKs are only written to an explicitly requested owner-only file.
• Fix: Studio compat calls no longer leak connection options or API tokens, or drop cover images; errors distinguish permission, quota and conflicts; anonymous Studio info and log pagination work
• Enhance: MCP verb negotiation and Studio-owner listings adapt to endpoint behaviour
• Quality: the vendored OpenAPI spec and operation registry flag unimplemented published Agent-IDP, MCP, and Studios endpoints

v0.3.1 (2026-09-01)

• Refactor: upload environment variables now state their units and semantics; deprecated names remain supported with warnings
• Fix: logout works; download locks avoid same-basename contention; whoami and legacy responses normalise pre-production field names

v0.3.0 (2026-08-19)

• Feature: this package owns all four console scripts (modelscope, ms, modelscope-hub, ms-hub), adds HubApi.get_current_username(), and supports both agent visibility wire formats
• Fix: large repo/files listings are re-enumerated when the server silently truncates results

Installation

pip install modelscope-hub

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

Command names

This package installs every ModelScope console script, and all four are the same program — pick whichever reads best in your shell:

Owning all four in one distribution is deliberate: when the umbrella modelscope SDK also declared modelscope / ms, installing or upgrading either package could overwrite or delete the other's scripts and leave you with no CLI at all. OS packagers (such as FreeBSD pkg) likewise refuse to let two ports own the same path. The SDK now contributes its extra commands as plugins instead.

So modelscope and ms work on a hub-only install too. Commands that belong to the full SDK (pipeline, server, studio, modelcard, …) appear once you also pip install modelscope; until then --help says so. The two *-hub aliases always report just this package, which is handy for scripts that must pin the lightweight client:

ms-hub --version      # modelscope-hub X.Y.Z
modelscope --version  # modelscope A.B.C (modelscope-hub X.Y.Z)

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

Token permission levels

Tokens are issued with one of three permission levels, set when you create the token at modelscope.cn/my/myaccesstoken:

What this means in practice:

• A read-only token can log in. ms-hub login succeeds and prints a warning that git and session credentials were not issued, so pushes and uploads will need a write token. Downloads and browsing work normally.
• A rejected write is explicit. Attempting a write with a read-only token fails with [E3002] Permission denied and a suggestion naming the level the operation requires, rather than leaving you to guess.
• Quota exhaustion is not a permission problem. The service reports both as HTTP 403; the SDK separates them into PermissionDeniedError and QuotaExceededError (the latter is never retried, since retrying an exhausted quota only delays the error).
• Public reads never fail because of a token. For public endpoints the SDK retries once without credentials, so a read-scoped or stale token cannot hide data any anonymous caller can see.

The SDK cannot tell you which level your token has: the API does not report it. Check the token settings page if you are unsure.

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 list --repo-type studio --owner my-org
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 / ms-hub studio variable

Manage a Studio's environment variables. Two commands, because the disclosure differs: a secret's value is never returned by the API, a variable's value is publicly visible.

# Secrets — values are write-only
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

# Plaintext variables — values are readable by anyone
ms-hub studio variable add my-org/demo MODEL_NAME Qwen2.5-7B
ms-hub studio variable list my-org/demo
ms-hub studio variable update my-org/demo MODEL_NAME Qwen2.5-14B
ms-hub studio variable delete my-org/demo MODEL_NAME --yes

ms-hub studio

Browse Studio spaces and the runtime resources they can be configured with.

# Browse
ms-hub studio list --search chat --sort likes --page-size 20
ms-hub studio list --owner my-org --status all
ms-hub studio list --mcp-support --hardware-type xgpu

# Discover valid values for --hardware / --base-image / --sdk-version
ms-hub studio hardware --sdk-type gradio
ms-hub studio hardware --studio my-org/demo
ms-hub studio base-images
ms-hub studio sdk-versions --sdk-type gradio

# Runtime management (also available as the top-level deploy/stop/logs/settings)
ms-hub studio deploy my-org/demo
ms-hub studio logs my-org/demo --type build
ms-hub studio settings my-org/demo --visibility protected

ms-hub mcp

Manage MCP (Model Context Protocol) servers.

ms-hub mcp list --search weather --page-size 10
ms-hub mcp list --hosted            # only your own hosted servers, with live URLs
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

Remote agent repositories: raw file transfer (download, upload, list) and plugin-driven install.

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
ms-hub agent install  -r user/my-agent                          # install into the framework

download / upload / list transfer files as-is, with no framework awareness.

install is different: it fetches an official plugin and hands the agent id to it, leaving every framework decision to the plugin. See ms-hub agent install for the details and the security model.

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

ms-hub agent install -r user/my-agent

plugin: modelscope/agent-hub-plugin@v0.3.1 (version 0.3.1)
entry : agent_hub_plugin.install()          # negotiated: install > fetch_raw > download
scope : frameworks ms-agent, qwenpaw | operations fetch_raw, install, list_backups, restore | planned convert (P2), upload (P1)
Installed user/my-agent

from modelscope_hub.agent import install_agent

outcome = install_agent("owner/my-agent", plugin_revision="v0.3.1")
print(outcome.ok, outcome.operation, outcome.exit_code, outcome.error)

ms-hub agent-idp

Agent-IDP manages an Agent's identity and signing key, not its repository files. Use ms-hub agent for raw Agent repository transfer; use ms-hub agent-idp to register an Ed25519 public key, inspect OIDC metadata, and issue a short-lived JWT.

# Private JWK storage is always explicit; the command prints only its public JWK.
ms-hub agent-idp keygen --private-key-out ./agent.jwk
ms-hub agent-idp create --agent-name my-agent --private-key-file ./agent.jwk
ms-hub agent-idp issue-token --agent-id agent_id:modelscope:agent_xxx --audience my-hub --private-key-file ./agent.jwk

# These discovery endpoints are public and do not require login.
ms-hub agent-idp configuration
ms-hub agent-idp jwks

Protect the private JWK file: it is created with mode 0600 on POSIX, never copied into the SDK configuration or cache, and must not be committed. External key stores can pass a public JWK with --public-jwk-file for registration or rotation.

from modelscope_hub import HubApi, generate_agent_key_pair

api = HubApi(token="ms-write-token")
private_jwk, public_jwk = generate_agent_key_pair()
identity = api.create_agent_identity({"agent_name": "my-agent", "public_key": public_jwk.to_dict()})
token = api.issue_agent_token_with_private_key(private_jwk, agent_id=identity.agent_id, audience="my-hub")

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}
}