diff --git a/.github/workflows/test-rust-package.yaml b/.github/workflows/test-rust-package.yaml
index 6f403964c6..0c2ec449bc 100644
--- a/.github/workflows/test-rust-package.yaml
+++ b/.github/workflows/test-rust-package.yaml
@@ -12,11 +12,12 @@ concurrency:
 
 jobs:
   test-rust-package:
+    name: Test ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, macos-15-intel, ubuntu-22.04-arm]
+        os: [ubuntu-latest, macos-latest, macos-15-intel, ubuntu-22.04-arm, windows-latest]
 
     env:
       # Placeholder, will be overwritten per OS
@@ -32,6 +33,22 @@ jobs:
         with:
           toolchain: stable
 
+      - name: Set up MSVC
+        if: matrix.os == 'windows-latest'
+        uses: ilammy/msvc-dev-cmd@v1
+
+      - name: Select MSVC linker
+        if: matrix.os == 'windows-latest'
+        shell: pwsh
+        run: |
+          $linker = Join-Path $env:VCToolsInstallDir 'bin\HostX64\x64\link.exe'
+          if (-not (Test-Path $linker)) {
+            throw "MSVC linker not found: $linker"
+          }
+          "CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER=$linker" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          Write-Host "Using linker: $linker"
+          & where.exe link
+
       # Download prebuilt libraries depending on OS
       - name: Download prebuilt Sherpa-ONNX libraries
         shell: bash
@@ -46,6 +63,8 @@ jobs:
             d=sherpa-onnx-v$SHERPA_ONNX_VERSION-linux-x64-shared
           elif [[ "${{ matrix.os }}" == "ubuntu-22.04-arm" ]]; then
             d=sherpa-onnx-v$SHERPA_ONNX_VERSION-linux-aarch64-shared-cpu
+          elif [[ "${{ matrix.os }}" == "windows-latest" ]]; then
+            d=sherpa-onnx-v$SHERPA_ONNX_VERSION-win-x64-shared-MT-Release
           else
             echo "Unknown ${{ matrix.os }}"
             exit 1
@@ -60,7 +79,16 @@ jobs:
 
           # Export environment variables for this step
           echo "SHERPA_ONNX_LIB_DIR=$PWD/$d/lib" >> $GITHUB_ENV
-          echo "RUSTFLAGS=-C link-arg=-Wl,-rpath,$PWD/$d/lib" >> $GITHUB_ENV
+          if [[ "${{ matrix.os }}" == "windows-latest" ]]; then
+            if [[ -d "$PWD/$d/bin" ]]; then
+              echo "$PWD/$d/bin" >> $GITHUB_PATH
+              ls -lh $d/bin
+            fi
+            echo "$PWD/$d/lib" >> $GITHUB_PATH
+            echo "RUSTFLAGS=" >> $GITHUB_ENV
+          else
+            echo "RUSTFLAGS=-C link-arg=-Wl,-rpath,$PWD/$d/lib" >> $GITHUB_ENV
+          fi
 
       - name: Show libs
         shell: bash
@@ -69,8 +97,17 @@ jobs:
           ls -lh $SHERPA_ONNX_LIB_DIR
 
           echo "RUSTFLAGS: $RUSTFLAGS"
+          if [[ "${{ matrix.os }}" == "windows-latest" ]]; then
+            echo "CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER: $CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER"
+          fi
 
       - name: Run test
         shell: bash
         run: |
+          if [[ "${{ matrix.os }}" == "windows-latest" ]]; then
+            export PATH="$SHERPA_ONNX_LIB_DIR:$PATH"
+            mkdir -p rust-api-examples/target/debug/examples
+            cp -v "$SHERPA_ONNX_LIB_DIR"/*.dll rust-api-examples/target/debug/examples/
+            ls -lh rust-api-examples/target/debug/examples/
+          fi
           ./.github/scripts/test-rust.sh
diff --git a/.github/workflows/windows-arm64.yaml b/.github/workflows/windows-arm64.yaml
index 42d79737df..6c3ae3c7da 100644
--- a/.github/workflows/windows-arm64.yaml
+++ b/.github/workflows/windows-arm64.yaml
@@ -179,6 +179,14 @@ jobs:
           cp -a build/install/lib $dst/
           cp -a build/install/include $dst/
 
+          if [[ $shared_lib == "ON" && -f build/install/lib/onnxruntime.lib ]]; then
+            cp -v build/install/lib/onnxruntime.lib $dst/lib/
+          fi
+
+          rm -rf $dst/lib/pkgconfig
+          rm -f $dst/lib/cargs.dll $dst/lib/cargs.lib $dst/lib/cargs.h
+          rm -f $dst/include/cargs.h
+
           ls -lh $dst/bin/
           echo "---"
           ls -lh $dst/lib/
diff --git a/.github/workflows/windows-x64.yaml b/.github/workflows/windows-x64.yaml
index d54ba21b87..024b469d90 100644
--- a/.github/workflows/windows-x64.yaml
+++ b/.github/workflows/windows-x64.yaml
@@ -191,6 +191,14 @@ jobs:
           cp -a build/install/lib $dst/
           cp -a build/install/include $dst/
 
+          if [[ $shared_lib == "ON" && -f build/install/lib/onnxruntime.lib ]]; then
+            cp -v build/install/lib/onnxruntime.lib $dst/lib/
+          fi
+
+          rm -rf $dst/lib/pkgconfig
+          rm -f $dst/lib/cargs.dll $dst/lib/cargs.lib $dst/lib/cargs.h
+          rm -f $dst/include/cargs.h
+
           ls -lh $dst/bin/
           echo "---"
           ls -lh $dst/lib/
@@ -244,7 +252,7 @@ jobs:
           file: sherpa-onnx-*-win-x64*.tar.bz2
           repo_name: k2-fsa/sherpa-onnx
           repo_token: ${{ secrets.UPLOAD_GH_SHERPA_ONNX_TOKEN }}
-          tag: v1.12.28
+          tag: v1.12.31
 
       - name: Release pre-compiled binaries and libs for Windows x64
         if: github.repository_owner == 'k2-fsa'&& github.event_name == 'push' && contains(github.ref, 'refs/tags/')
diff --git a/.github/workflows/windows-x86.yaml b/.github/workflows/windows-x86.yaml
index 2babda0dc8..ad1e2210b9 100644
--- a/.github/workflows/windows-x86.yaml
+++ b/.github/workflows/windows-x86.yaml
@@ -185,6 +185,14 @@ jobs:
           cp -a build/install/lib $dst/
           cp -a build/install/include $dst/
 
+          if [[ $shared_lib == "ON" && -f build/install/lib/onnxruntime.lib ]]; then
+            cp -v build/install/lib/onnxruntime.lib $dst/lib/
+          fi
+
+          rm -rf $dst/lib/pkgconfig
+          rm -f $dst/lib/cargs.dll $dst/lib/cargs.lib $dst/lib/cargs.h
+          rm -f $dst/include/cargs.h
+
           ls -lh $dst/bin/
           echo "---"
           ls -lh $dst/lib/
diff --git a/CMakeLists.txt b/CMakeLists.txt
index c8ee79dfe2..244238f760 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -126,7 +126,7 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 
-if(NOT WIN32)
+if(UNIX)
   set(CMAKE_SKIP_BUILD_RPATH FALSE)
   set(BUILD_RPATH_USE_ORIGIN TRUE)
   set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
@@ -138,7 +138,7 @@ else()
   set(SHERPA_ONNX_RPATH_ORIGIN "@loader_path")
 endif()
 
-if(NOT WIN32)
+if(UNIX)
   set(CMAKE_INSTALL_RPATH ${SHERPA_ONNX_RPATH_ORIGIN})
   set(CMAKE_BUILD_RPATH ${SHERPA_ONNX_RPATH_ORIGIN})
 endif()
diff --git a/cmake/onnxruntime-win-arm64.cmake b/cmake/onnxruntime-win-arm64.cmake
index 5d770ba364..ec73f10309 100644
--- a/cmake/onnxruntime-win-arm64.cmake
+++ b/cmake/onnxruntime-win-arm64.cmake
@@ -107,3 +107,4 @@ message(STATUS "onnxruntime lib files: ${onnxruntime_lib_files}")
 
 install(FILES ${onnxruntime_lib_files} DESTINATION lib)
 install(FILES ${onnxruntime_lib_files} DESTINATION bin)
+install(FILES "${onnxruntime_SOURCE_DIR}/lib/onnxruntime.lib" DESTINATION lib)
diff --git a/cmake/onnxruntime-win-x64.cmake b/cmake/onnxruntime-win-x64.cmake
index c2f6fba78d..958073e651 100644
--- a/cmake/onnxruntime-win-x64.cmake
+++ b/cmake/onnxruntime-win-x64.cmake
@@ -107,3 +107,4 @@ message(STATUS "onnxruntime lib files: ${onnxruntime_lib_files}")
 
 install(FILES ${onnxruntime_lib_files} DESTINATION lib)
 install(FILES ${onnxruntime_lib_files} DESTINATION bin)
+install(FILES "${onnxruntime_SOURCE_DIR}/lib/onnxruntime.lib" DESTINATION lib)
diff --git a/cmake/onnxruntime-win-x86.cmake b/cmake/onnxruntime-win-x86.cmake
index 3fe0bd2aed..4b2eaa39d7 100644
--- a/cmake/onnxruntime-win-x86.cmake
+++ b/cmake/onnxruntime-win-x86.cmake
@@ -107,3 +107,4 @@ message(STATUS "onnxruntime lib files: ${onnxruntime_lib_files}")
 
 install(FILES ${onnxruntime_lib_files} DESTINATION lib)
 install(FILES ${onnxruntime_lib_files} DESTINATION bin)
+install(FILES "${onnxruntime_SOURCE_DIR}/lib/onnxruntime.lib" DESTINATION lib)
diff --git a/new-release.sh b/new-release.sh
index 8ed04aa1f6..8c7d023093 100755
--- a/new-release.sh
+++ b/new-release.sh
@@ -37,6 +37,7 @@ sed -i.bak "$replace_str" ./android/SherpaOnnxAar/README.md
 sed -i.bak "$replace_str" ./rust-api-examples/Cargo.toml
 sed -i.bak "$replace_str" ./sherpa-onnx/rust/sherpa-onnx-sys/Cargo.toml
 sed -i.bak "$replace_str" ./sherpa-onnx/rust/sherpa-onnx/Cargo.toml
+sed -i.bak "$replace_str" ./sherpa-onnx/rust/sherpa-onnx/src/lib.rs
 sed -i.bak "$replace_str" ./rust-api-examples/README.md
 
 find android -name build.gradle -type f -exec sed -i.bak "s/sherpa-onnx:v$old_version/sherpa-onnx:v$new_version/g" {} \;
diff --git a/rust-api-examples/README.md b/rust-api-examples/README.md
index 2112fa228c..1649372097 100644
--- a/rust-api-examples/README.md
+++ b/rust-api-examples/README.md
@@ -1,25 +1,88 @@
 # Introduction
 
-This folder uses Rust API maintained by us.
+This folder contains examples that use the `sherpa-onnx` Rust crate maintained in
+this repository.
 
-## Setup library path
+## Setup
 
-### Method 1 (Build from source, support only shared libs right now)
+The Rust crate needs to find the sherpa-onnx shared libraries at build time, and
+your operating system needs to find them again at run time.
+
+There are two common ways to do that:
+
+- Method 1: Build sherpa-onnx from source and use the generated shared libraries
+- Method 2: Download a prebuilt sherpa-onnx shared-library package from GitHub releases
+
+### Method 1: Build from source
+
+Build and install sherpa-onnx first. After that, point `SHERPA_ONNX_LIB_DIR` to
+the generated `lib` directory.
+
+#### Linux
+
+```bash
+export SHERPA_ONNX_LIB_DIR=/path/to/sherpa-onnx/build/install/lib
+export RUSTFLAGS="-C link-arg=-Wl,-rpath,$SHERPA_ONNX_LIB_DIR"
+```
+
+#### macOS
 
 ```bash
-export SHERPA_ONNX_LIB_DIR=/Users/fangjun/open-source/sherpa-onnx/build/install/lib
+export SHERPA_ONNX_LIB_DIR=/path/to/sherpa-onnx/build/install/lib
 export RUSTFLAGS="-C link-arg=-Wl,-rpath,$SHERPA_ONNX_LIB_DIR"
 ```
 
-### Method 2 (Download pre-built libs)
+#### Windows
+
+```bash
+export SHERPA_ONNX_LIB_DIR=/path/to/sherpa-onnx/build/install/lib
+export PATH="$SHERPA_ONNX_LIB_DIR:$PATH"
+```
+
+If Windows still reports that it cannot find a DLL, or if it loads a wrong
+`onnxruntime.dll`, copy the DLL files from `%SHERPA_ONNX_LIB_DIR%` to the same
+directory as the generated example executable, e.g.
+`rust-api-examples/target/debug/examples/`.
+
+### Method 2: Download prebuilt shared libraries
+
+This is the easiest method for most users.
+
+1. Go to [GitHub releases](https://github.com/k2-fsa/sherpa-onnx/releases)
+2. Download the archive that matches your operating system
+3. Extract it anywhere you like
+4. Set `SHERPA_ONNX_LIB_DIR` to the extracted `lib` directory
+5. On Linux/macOS, also set `RUSTFLAGS` so the executable can find the shared libraries
+6. On Windows, add the same `lib` directory to `PATH`
+
+Use the latest release in practice. We use `v1.12.31` below only as an example.
+
+#### Which archive should I download?
+
+| OS | Archive example | Download link |
+|----|-----------------|---------------|
+| Linux x86_64 | `sherpa-onnx-v1.12.31-linux-x64-shared.tar.bz2` | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-linux-x64-shared.tar.bz2) |
+| Linux aarch64 | `sherpa-onnx-v1.12.31-linux-aarch64-shared-cpu.tar.bz2` | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-linux-aarch64-shared-cpu.tar.bz2) |
+| macOS | `sherpa-onnx-v1.12.31-osx-universal2-shared.tar.bz2` | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-osx-universal2-shared.tar.bz2) |
+| Windows x64 | `sherpa-onnx-v1.12.31-win-x64-shared-MT-Release.tar.bz2` | [Download](https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-win-x64-shared-MT-Release.tar.bz2) |
+
+#### Linux
 
 ```bash
-# You can choose any directory you like
 cd $HOME/Downloads
 
-# We use version v1.12.31 below as an example.
-# Please always use the latest version from
-# https://github.com/k2-fsa/sherpa-onnx/releases
+wget https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-linux-x64-shared.tar.bz2
+tar xvf sherpa-onnx-v1.12.31-linux-x64-shared.tar.bz2
+rm sherpa-onnx-v1.12.31-linux-x64-shared.tar.bz2
+
+export SHERPA_ONNX_LIB_DIR=$HOME/Downloads/sherpa-onnx-v1.12.31-linux-x64-shared/lib
+export RUSTFLAGS="-C link-arg=-Wl,-rpath,$SHERPA_ONNX_LIB_DIR"
+```
+
+#### macOS
+
+```bash
+cd $HOME/Downloads
 
 wget https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-osx-universal2-shared.tar.bz2
 tar xvf sherpa-onnx-v1.12.31-osx-universal2-shared.tar.bz2
@@ -29,6 +92,26 @@ export SHERPA_ONNX_LIB_DIR=$HOME/Downloads/sherpa-onnx-v1.12.31-osx-universal2-s
 export RUSTFLAGS="-C link-arg=-Wl,-rpath,$SHERPA_ONNX_LIB_DIR"
 ```
 
+#### Windows
+
+```bash
+cd /c/Users/$USERNAME/Downloads
+
+curl -SL -O https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-win-x64-shared-MT-Release.tar.bz2
+tar xvf sherpa-onnx-v1.12.31-win-x64-shared-MT-Release.tar.bz2
+rm sherpa-onnx-v1.12.31-win-x64-shared-MT-Release.tar.bz2
+
+export SHERPA_ONNX_LIB_DIR=/c/Users/$USERNAME/Downloads/sherpa-onnx-v1.12.31-win-x64-shared-MT-Release/lib
+export PATH="$SHERPA_ONNX_LIB_DIR:$PATH"
+```
+
+In most cases, updating `PATH` is enough on Windows. If an example still loads
+the wrong `onnxruntime.dll`, copy the DLL files from
+`$SHERPA_ONNX_LIB_DIR` to `target/debug/examples/` and run the example again.
+
+After setting the environment variables above, you can run the examples in this
+directory with `cargo run --example ...` or use the helper scripts below.
+
 ## Examples
 
 | # | Example | Description |
diff --git a/rust-api-examples/run-zipvoice-tts.sh b/rust-api-examples/run-zipvoice-tts.sh
index 2b4e9dde77..4ec898a727 100755
--- a/rust-api-examples/run-zipvoice-tts.sh
+++ b/rust-api-examples/run-zipvoice-tts.sh
@@ -3,7 +3,7 @@ set -ex
 
 if [ ! -f ./sherpa-onnx-zipvoice-distill-int8-zh-en-emilia/encoder.int8.onnx ]; then
   curl -SL -O https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/sherpa-onnx-zipvoice-distill-int8-zh-en-emilia.tar.bz2
-  tar xvf sherpa-onnx-zipvoice-distill-int8-zh-en-emilia.tar.bz2
+  tar xf sherpa-onnx-zipvoice-distill-int8-zh-en-emilia.tar.bz2
   rm sherpa-onnx-zipvoice-distill-int8-zh-en-emilia.tar.bz2
 fi
 
diff --git a/sherpa-onnx/csrc/CMakeLists.txt b/sherpa-onnx/csrc/CMakeLists.txt
index 2d52a73264..84e115d88c 100755
--- a/sherpa-onnx/csrc/CMakeLists.txt
+++ b/sherpa-onnx/csrc/CMakeLists.txt
@@ -522,7 +522,7 @@ if(SHERPA_ONNX_ENABLE_BINARY)
     target_link_libraries(${exe} sherpa-onnx-core)
   endforeach()
 
-  if(NOT WIN32)
+  if(UNIX)
     foreach(exe IN LISTS main_exes)
       target_link_libraries(${exe} "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../lib")
       target_link_libraries(${exe} "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../../../sherpa_onnx/lib")
@@ -597,7 +597,7 @@ if(SHERPA_ONNX_HAS_ALSA AND SHERPA_ONNX_ENABLE_BINARY)
     endif()
   endforeach()
 
-  if(NOT WIN32)
+  if(UNIX)
     foreach(exe IN LISTS exes)
       target_link_libraries(${exe} "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../lib")
       target_link_libraries(${exe} "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../../../sherpa_onnx/lib")
@@ -702,7 +702,7 @@ if(SHERPA_ONNX_ENABLE_PORTAUDIO AND SHERPA_ONNX_ENABLE_BINARY)
     target_link_libraries(${exe} portaudio_static sherpa-onnx-core)
   endforeach()
 
-  if(NOT WIN32)
+  if(UNIX)
     foreach(exe IN LISTS exes)
       target_link_libraries(${exe} "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../lib")
       target_link_libraries(${exe} "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../../../sherpa_onnx/lib")
@@ -743,7 +743,7 @@ if(SHERPA_ONNX_ENABLE_WEBSOCKET AND SHERPA_ONNX_ENABLE_BINARY)
   )
   target_link_libraries(sherpa-onnx-online-websocket-client sherpa-onnx-core)
 
-  if(NOT WIN32)
+  if(UNIX)
     target_compile_options(sherpa-onnx-online-websocket-server PRIVATE -Wno-deprecated-declarations)
 
     target_compile_options(sherpa-onnx-online-websocket-client PRIVATE -Wno-deprecated-declarations)
@@ -756,11 +756,11 @@ if(SHERPA_ONNX_ENABLE_WEBSOCKET AND SHERPA_ONNX_ENABLE_BINARY)
   )
   target_link_libraries(sherpa-onnx-offline-websocket-server sherpa-onnx-core)
 
-  if(NOT WIN32)
+  if(UNIX)
     target_compile_options(sherpa-onnx-offline-websocket-server PRIVATE -Wno-deprecated-declarations)
   endif()
 
-  if(NOT WIN32)
+  if(UNIX)
     target_link_libraries(sherpa-onnx-online-websocket-server "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../lib")
     target_link_libraries(sherpa-onnx-online-websocket-server "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../../../sherpa_onnx/lib")
 
@@ -770,7 +770,7 @@ if(SHERPA_ONNX_ENABLE_WEBSOCKET AND SHERPA_ONNX_ENABLE_BINARY)
     target_link_libraries(sherpa-onnx-offline-websocket-server "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../lib")
     target_link_libraries(sherpa-onnx-offline-websocket-server "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../../../sherpa_onnx/lib")
 
-    if(SHERPA_ONNX_ENABLE_PYTHON AND NOT WIN32)
+    if(SHERPA_ONNX_ENABLE_PYTHON)
       target_link_libraries(sherpa-onnx-online-websocket-server "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../lib/python${PYTHON_VERSION}/site-packages/sherpa_onnx/lib")
       target_link_libraries(sherpa-onnx-online-websocket-client "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../lib/python${PYTHON_VERSION}/site-packages/sherpa_onnx/lib")
       target_link_libraries(sherpa-onnx-offline-websocket-server "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/../lib/python${PYTHON_VERSION}/site-packages/sherpa_onnx/lib")
diff --git a/sherpa-onnx/python/csrc/CMakeLists.txt b/sherpa-onnx/python/csrc/CMakeLists.txt
index a832c9c4cb..740d102136 100644
--- a/sherpa-onnx/python/csrc/CMakeLists.txt
+++ b/sherpa-onnx/python/csrc/CMakeLists.txt
@@ -111,7 +111,7 @@ if(APPLE)
   endif()
 endif()
 
-if(NOT WIN32)
+if(UNIX)
   target_link_libraries(_sherpa_onnx PRIVATE "-Wl,-rpath,${SHERPA_ONNX_RPATH_ORIGIN}/sherpa_onnx/lib")
 endif()
 
diff --git a/sherpa-onnx/rust/.gitignore b/sherpa-onnx/rust/.gitignore
index 648731f7ab..af623a0581 100644
--- a/sherpa-onnx/rust/.gitignore
+++ b/sherpa-onnx/rust/.gitignore
@@ -1,2 +1,3 @@
 notes.md
 target
+Cargo.lock
diff --git a/sherpa-onnx/rust/sherpa-onnx-sys/build.rs b/sherpa-onnx/rust/sherpa-onnx-sys/build.rs
index 80f29b4812..53d44c7c70 100644
--- a/sherpa-onnx/rust/sherpa-onnx-sys/build.rs
+++ b/sherpa-onnx/rust/sherpa-onnx-sys/build.rs
@@ -21,8 +21,9 @@ fn main() {
         }
     }
 
-    // Link the dynamic libraries regardless (cargo will fail later if not found)
+    // Always link against the public sherpa-onnx C API import library.
     println!("cargo:rustc-link-lib=dylib=sherpa-onnx-c-api");
+
     println!("cargo:rustc-link-lib=dylib=onnxruntime");
 
     // Rebuild if the env variable changes
diff --git a/sherpa-onnx/rust/sherpa-onnx/src/lib.rs b/sherpa-onnx/rust/sherpa-onnx/src/lib.rs
index 1734706afe..eac819ad5a 100644
--- a/sherpa-onnx/rust/sherpa-onnx/src/lib.rs
+++ b/sherpa-onnx/rust/sherpa-onnx/src/lib.rs
@@ -13,6 +13,58 @@
 //! - audio tagging
 //! - WAV I/O helpers through [`Wave`] and [`write()`]
 //!
+//! # Setup
+//!
+//! This crate links against the public sherpa-onnx shared libraries. You need
+//! to make those libraries visible both when Cargo links your program and when
+//! your operating system loads the executable at runtime.
+//!
+//! There are two common ways to do that:
+//!
+//! - build sherpa-onnx from source and use the generated shared libraries
+//! - download a prebuilt shared-library package from
+//!   [GitHub releases](https://github.com/k2-fsa/sherpa-onnx/releases)
+//!
+//! In both cases, set `SHERPA_ONNX_LIB_DIR` to the directory that contains the
+//! sherpa-onnx shared libraries.
+//!
+//! Example download URLs for `v1.12.31`:
+//!
+//! - Linux x86_64:
+//!   [sherpa-onnx-v1.12.31-linux-x64-shared.tar.bz2](https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-linux-x64-shared.tar.bz2)
+//! - Linux aarch64:
+//!   [sherpa-onnx-v1.12.31-linux-aarch64-shared-cpu.tar.bz2](https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-linux-aarch64-shared-cpu.tar.bz2)
+//! - macOS:
+//!   [sherpa-onnx-v1.12.31-osx-universal2-shared.tar.bz2](https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-osx-universal2-shared.tar.bz2)
+//! - Windows x64:
+//!   [sherpa-onnx-v1.12.31-win-x64-shared-MT-Release.tar.bz2](https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.31/sherpa-onnx-v1.12.31-win-x64-shared-MT-Release.tar.bz2)
+//!
+//! ## Linux
+//!
+//! ```bash
+//! export SHERPA_ONNX_LIB_DIR=/path/to/sherpa-onnx/lib
+//! export RUSTFLAGS="-C link-arg=-Wl,-rpath,$SHERPA_ONNX_LIB_DIR"
+//! ```
+//!
+//! ## macOS
+//!
+//! ```bash
+//! export SHERPA_ONNX_LIB_DIR=/path/to/sherpa-onnx/lib
+//! export RUSTFLAGS="-C link-arg=-Wl,-rpath,$SHERPA_ONNX_LIB_DIR"
+//! ```
+//!
+//! ## Windows
+//!
+//! ```bash
+//! export SHERPA_ONNX_LIB_DIR=/path/to/sherpa-onnx/lib
+//! export PATH="$SHERPA_ONNX_LIB_DIR:$PATH"
+//! ```
+//!
+//! If Windows still loads the wrong `onnxruntime.dll`, copy the DLL files from
+//! `SHERPA_ONNX_LIB_DIR` to the same directory as your executable. For example,
+//! when using the examples in this repository, that directory is usually
+//! `rust-api-examples/target/debug/examples/`.
+//!
 //! # How the Rust API is organized
 //!
 //! Most APIs follow the same pattern: