Use this guide for from funasr import AutoModel. For a packaged C++ service, start with Docker and runtime images. After installation, continue to the SDK tutorial.

1. Create an isolated environment

The commands below use an already installed Python 3.11 interpreter. This is an environment example, not a promise that every model/backend supports every Python version. setup.py declares python_requires=">=3.7.0", but resolved dependencies and individual models can require newer Python. pyproject.toml defines the build backend, not a locked inference environment.

Linux/macOS:

python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip

Windows PowerShell:

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

An existing Conda environment is also suitable; see the Conda installation reference. On Apple Silicon, use an arm64 interpreter and matching wheels throughout; do not mix an x86_64 Conda environment with arm64 packages.

2. Install PyTorch, then choose one FunASR route

Install matching torch and torchaudio builds for your interpreter, OS, and accelerator using the PyTorch installer or version compatibility reference. FunASR's core package does not select these builds for you. Do not infer wheel compatibility solely from a locally installed CUDA toolkit.

PyPI: use a released package

python -m pip install --upgrade funasr

This installs the package available from your configured index, not the current Git checkout. A model or feature documented in this checkout may not be in that release. For reproducible work, replace the unpinned install with the exact version you have validated. Package version for this checkout is recorded in version.txt; it is not evidence of index availability.

Source: use this checkout and its examples

From the root of an existing FunASR checkout:

python -m pip install -e .
git rev-parse HEAD

For a new checkout, the repository can be cloned first:

git clone https://github.com/modelscope/FunASR.git
cd FunASR
python -m pip install -e .

Editable installation imports code from that directory; record its commit and local modifications. It is not a separate copy of the code. The repository's examples/, runtime/, and documentation are not all installed as Python package data by a PyPI install.

In this checkout, modelscope and huggingface_hub are core dependencies, not optional follow-up installs. Model-specific extras remain separate. The knf extra provides kaldi-native-fbank for supported paths without torchaudio, and silero provides Silero VAD; neither is needed for the standard first example. Check setup.py and the chosen model's guide before adding extras. Do not install conflicting model stacks into one environment.

3. Verify the interpreter and imports

Run from the same activated environment you will use for inference:

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version
python -m pip check
python -c "import funasr, torch, torchaudio; from funasr import AutoModel; print('funasr:', funasr.__version__, funasr.__file__); print('torch:', torch.__version__, 'torchaudio:', torchaudio.__version__); print('CUDA available:', torch.cuda.is_available()); print('AutoModel import OK')"

These are dependency/import checks, not a model download or inference test. funasr.__file__ should point to the intended installation; run outside unrelated checkouts when checking a PyPI environment. CPU is an explicit starting choice in the tutorial. A successful import or accelerator availability check does not validate an individual model on that device.

For a registration/import failure in this source checkout, inspect funasr.get_import_errors() or set FUNASR_IMPORT_DEBUG=1 before starting Python. Missing optional model dependencies do not necessarily block your selected model. See troubleshooting before upgrading the entire environment.

4. Models, cache, and offline use

AutoModel accepts a model ID/alias or an existing local model directory. hub="ms" is the default; hub="hf" selects Hugging Face. Model files download separately from the Python package and use the hub client's cache. After loading, model.model_path identifies the resolved directory. Ensure enough writable disk space and preserve the complete directory, including configuration, tokenizer, frontend assets, and weights.

For repeatable or disconnected runs:

On an approved connected machine, acquire the exact model snapshot and dependencies. Record the full model ID, hub revision/commit, license, package versions, and file checksums. Also prepare every VAD, punctuation, or speaker model you plan to load.
Transfer complete model directories and dependency artifacts. Replace all hub aliases with those directories and all input URLs with local files. Check configuration references for other remote dependencies.
Use disable_update=True to skip FunASR's startup version check. This is not an offline switch for hub clients, model code, or missing assets. Validate the prepared environment with outbound network access disabled.

The following Python example requires a complete, reviewed Paraformer-compatible snapshot at ./models/paraformer-zh and your local ./audio.wav:

from pathlib import Path
from funasr import AutoModel

model_dir = Path("./models/paraformer-zh").resolve()
audio = Path("./audio.wav").resolve()
assert model_dir.is_dir(), model_dir
assert audio.is_file(), audio
model = AutoModel(
    model=str(model_dir), device="cpu", disable_update=True,
    trust_remote_code=False,
)
print(model.generate(input=str(audio)))

Source caveat: the ModelScope helper passes model_revision to its downloader, but this checkout's Hugging Face helper calls snapshot_download(model) without forwarding the revision. Do not rely on AutoModel(..., hub="hf", model_revision=...) for pinning here; acquire a pinned snapshot with the hub client and pass its local directory. See the download implementation.

5. Trust and licensing

Leave trust_remote_code=False unless a chosen model requires code you have reviewed. In the loader, enabling trust can install a model's requirements.txt; the ModelScope path can also import the configured remote_code. A local model directory is not automatically safe.
Use isolated environments, reviewed model artifacts, and minimum filesystem/network permissions. Do not embed hub credentials in scripts, images, logs, or issue reports. Use the hub client's supported authentication mechanism.
FunASR software is MIT licensed. Model weights have separate terms; consult the exact model card and the Model Zoo. The model license agreement applies only where the model card adopts it. Third-party models retain their own provenance and licenses.

Next: produce your first transcript.