---
id: modelscope-hub
version: "0.2.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# modelscope-hub — The official Python client to connect with ModelScope Hub.

License: permissive · Maintenance: active · Downloads: 4.1M/mo

## What it is and what it does

modelscope-hub is the official Python SDK and CLI for interacting with ModelScope Hub, a repository hosting many AI models and datasets. It provides a single HubApi class and ms-hub command-line tool that unify operations across models, datasets, Studio spaces, skills, and MCP servers. The package handles the full lifecycle: authentication, downloading individual files or entire snapshots with resume capability and integrity checks, uploading files and folders, creating and managing repositories, and inspecting cached assets.

The package is built on ModelScope's OpenAPI surface with transparent fallback to legacy APIs for backward compatibility. Downloads include production-grade features like HTTP Range resume, parallel range download for large files, per-file retry with backoff, SHA256 verification, file locking for multiprocess safety, offline mode, and progress callbacks. The CLI supports filtering by file patterns, direct local-directory downloads that bypass the cache, and full repository lifecycle management including secret management and cache inspection.

Use it for:

- Download pre-trained models with pattern filtering to get only specific file types (e.g., .safetensors weights).
- Upload trained model weights or datasets to a personal or organizational ModelScope repository with commit messages and folder organization.
- Integrate ModelScope asset downloads into training or inference pipelines using the HubApi class with custom progress callbacks.
- Manage repository metadata, visibility, and gating settings from the CLI without visiting the web interface.
- Access cached models offline using local_files_only=True after an initial download, useful in air-gapped or low-bandwidth environments.
- Deploy MCP servers or Studio spaces and manage their operational URLs and environment variables from the terminal.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Download, upload, and manage AI models, datasets, and other assets on ModelScope Hub through a unified Python SDK and CLI interface.

Yes. The package is actively maintained, has low install friction, carries a permissive license, and solves a concrete problem for anyone working with ModelScope Hub assets. Recent releases show active bug fixes and error-handling improvements. No known vulnerabilities. Install if you need to programmatically or via CLI download, upload, or manage models and datasets on ModelScope Hub.

## Install

pip install modelscope-hub
uv add modelscope-hub
poetry add modelscope-hub

## Installing modelscope-hub

Before you install: Low friction install with four runtime dependencies (requests, tqdm, filelock, urllib3). Active maintenance — v0.2.0 released 2026-08-01 with bug fixes and error-handling improvements. Supports Python 3.10 through 3.14.

License in practice: Apache-2.0 permissive license — you can use, modify, and distribute freely, including in commercial projects, provided you include the license notice.

Quickstart:

pip install modelscope-hub

from modelscope_hub import HubApi

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

Requires Python 3.10 or later. ModelScope API token needed for authenticated operations (obtain from modelscope.cn/my/access/token or modelscope.ai/my/access/token).

Verify before relying:

- Whether the package handles authentication errors transparently across different ModelScope endpoints (v0.2.0 mentions endpoint probing but scope unclear).
- Performance characteristics of parallel range download for very large files (description mentions it but no benchmarks provided).
- Whether offline mode (local_files_only=True) works reliably across all repo types (models, datasets, studios, skills, MCP servers).

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 4.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

modelscope hub client, download models from modelscope, ai model repository management, modelscope sdk python, hub asset upload download, modelscope cli tool, machine learning model hub, model-hub, ml-ops, cli-tool

[View on SkillFed](https://skillfed.io/packages/modelscope-hub) · [View on PyPI](https://pypi.org/project/modelscope-hub/)