How to install Sentence Transformers with uv

Sentence embedding projects often use uv to keep dependency installation fast while still installing ordinary PyPI packages into an isolated Python environment. Sentence Transformers supports that workflow through uv pip, which installs the sentence-transformers package and its model-serving dependencies into the project virtual environment.

uv pip requires a target environment, and a default .venv directory gives uv a predictable place to install packages without activating the environment first. Creating the environment before the install also keeps PyTorch, Transformers, and Sentence Transformers out of the system Python.

The default install covers text embedding and reranking model loading. Add optional extras only when the project needs image, audio, video, training, ONNX, or OpenVINO support, and choose a PyTorch wheel that matches the machine's CPU or GPU runtime.

1. Open a terminal in the project directory.
2. Create a uv virtual environment for the project.

   $ uv venv --python 3.14
   Using CPython 3.14.4 interpreter at: /usr/bin/python3.14
   Creating virtual environment at: .venv
   Activate with: source .venv/bin/activate

   Omit --python 3.14 when the default Python on the machine is the version the project should use.

3. Install the CPU PyTorch wheel first when the project does not need CUDA acceleration.

   $ uv pip install --upgrade torch --index-url https://download.pytorch.org/whl/cpu
   Resolved 10 packages in 4.72s
   Downloading torch (143.1MiB)
   ##### snipped #####
   Installed 10 packages in 232ms
    + torch==2.12.1+cpu

   Use the install command from the PyTorch selector for CUDA, ROCm, or Apple Metal instead of the CPU index.
   Related: Enable PyTorch CUDA support

4. Install Sentence Transformers from PyPI in the .venv environment.

   $ uv pip install --upgrade sentence-transformers
   Resolved 40 packages in 511ms
   Downloading transformers (10.6MiB)
   Downloading scipy (32.4MiB)
   Downloading numpy (14.5MiB)
   ##### snipped #####
   Installed 33 packages in 90ms
    + sentence-transformers==5.6.0
    + transformers==5.12.1

   Quote extras when the project needs them, such as sentence-transformers[image], sentence-transformers[audio], sentence-transformers[video], sentence-transformers[train], sentence-transformers[onnx], sentence-transformers[onnx-gpu], or sentence-transformers[openvino].

5. Show the installed package metadata.

   $ uv pip show sentence-transformers
   Name: sentence-transformers
   Version: 5.6.0
   Location: /srv/apps/semantic-search/.venv/lib/python3.14/site-packages
   Requires: huggingface-hub, numpy, scikit-learn, scipy, torch, tqdm, transformers, typing-extensions
   Required-by:

   The exact version changes as new compatible releases appear on PyPI. The Location line should point inside the project .venv.

6. Check the installed dependency set.

   $ uv pip check
   Checked 40 packages in 0.56ms
   All installed packages are compatible

7. Import the package from the uv environment.

   $ uv run python -c "import sentence_transformers; print(sentence_transformers.__version__)"
   5.6.0

   The command should print a version without a traceback.