Installation

We recommend Python 3.10+, PyTorch 2.2+, and transformers v5.0+. There are several extra options to install Sentence Transformers:

  • Default: Allows loading, saving, and inference (i.e., getting embeddings) of text models.

  • Image: Adds dependencies for models that process images (e.g., CLIP, VLM-based models).

  • Audio: Adds dependencies for models that process audio inputs.

  • Video: Adds dependencies for models that process video inputs.

  • Training: Adds dependencies for training and finetuning models.

  • ONNX: Adds dependencies for loading, saving, inference, optimizing, and quantizing of models using the ONNX backend.

  • OpenVINO: Adds dependencies for loading, saving, and inference of models using the OpenVINO backend.

  • Development: All of the above plus some dependencies for developing Sentence Transformers, see Editable Install.

To pass torchcodec.AudioDecoder or torchcodec.VideoDecoder instances as inputs, you must install torchcodec separately, e.g. with: pip install torchcodec.
Note that you can mix and match the various extras, e.g. pip install -U "sentence-transformers[train,image,video,onnx-gpu]".

After installation, we recommend logging in to Hugging Face for higher Hugging Face Hub rate limits and access to private or gated models and datasets your account can read.

Install with uv

uv pip install -U sentence-transformers

uv pip install -U "sentence-transformers[image]"

uv pip install -U "sentence-transformers[audio]"

uv pip install -U "sentence-transformers[video]"

uv pip install -U "sentence-transformers[train]"

To use Weights and Biases or Trackio to track your training logs, you should also install wandb or trackio (recommended):

uv pip install trackio

And to track your carbon emissions while training and have this information automatically included in your model cards, also install codecarbon (recommended):

uv pip install codecarbon

Don’t forget to add the module names to report_to in the Training Arguments when training, or they will not be used.

For GPU and CPU:

uv pip install -U "sentence-transformers[onnx-gpu]"

For CPU only:

uv pip install -U "sentence-transformers[onnx]"

uv pip install -U "sentence-transformers[openvino]"

uv pip install -U "sentence-transformers[dev]"

Install with pip

pip install -U sentence-transformers

pip install -U "sentence-transformers[image]"

pip install -U "sentence-transformers[audio]"

pip install -U "sentence-transformers[video]"

pip install -U "sentence-transformers[train]"

To use Weights and Biases or Trackio to track your training logs, you should also install wandb or trackio (recommended):

pip install trackio

And to track your carbon emissions while training and have this information automatically included in your model cards, also install codecarbon (recommended):

pip install codecarbon

Don’t forget to add the module names to report_to in the Training Arguments when training, or they will not be used.

For GPU and CPU:

pip install -U "sentence-transformers[onnx-gpu]"

For CPU only:

pip install -U "sentence-transformers[onnx]"

pip install -U "sentence-transformers[openvino]"

pip install -U "sentence-transformers[dev]"

Install with Conda

The base package is available on conda-forge. Extras (e.g. [image], [train]) are a pip concept and not available via conda, so they are installed with pip.

conda install -c conda-forge sentence-transformers

pip install -U "sentence-transformers[image]"

pip install -U "sentence-transformers[audio]"

pip install -U "sentence-transformers[video]"

conda install -c conda-forge sentence-transformers accelerate datasets

To use Weights and Biases or Trackio to track your training logs, you should also install wandb or trackio (recommended):

pip install trackio

And to track your carbon emissions while training and have this information automatically included in your model cards, also install codecarbon (recommended):

pip install codecarbon

Don’t forget to add the module names to report_to in the Training Arguments when training, or they will not be used.

For GPU and CPU:

pip install -U "sentence-transformers[onnx-gpu]"

For CPU only:

pip install -U "sentence-transformers[onnx]"

pip install -U "sentence-transformers[openvino]"

conda install -c conda-forge sentence-transformers accelerate datasets pre-commit pytest ruff

Install from Source

You can install sentence-transformers directly from source to take advantage of the bleeding edge main branch rather than the latest stable release:

pip install git+https://github.com/huggingface/sentence-transformers.git

pip install -U "sentence-transformers[image] @ git+https://github.com/huggingface/sentence-transformers.git"

pip install -U "sentence-transformers[audio] @ git+https://github.com/huggingface/sentence-transformers.git"

pip install -U "sentence-transformers[video] @ git+https://github.com/huggingface/sentence-transformers.git"

pip install -U "sentence-transformers[train] @ git+https://github.com/huggingface/sentence-transformers.git"

To use Weights and Biases or Trackio to track your training logs, you should also install wandb or trackio (recommended):

pip install trackio

And to track your carbon emissions while training and have this information automatically included in your model cards, also install codecarbon (recommended):

pip install codecarbon

Don’t forget to add the module names to report_to in the Training Arguments when training, or they will not be used.

For GPU and CPU:

pip install -U "sentence-transformers[onnx-gpu] @ git+https://github.com/huggingface/sentence-transformers.git"

For CPU only:

pip install -U "sentence-transformers[onnx] @ git+https://github.com/huggingface/sentence-transformers.git"

pip install -U "sentence-transformers[openvino] @ git+https://github.com/huggingface/sentence-transformers.git"

pip install -U "sentence-transformers[dev] @ git+https://github.com/huggingface/sentence-transformers.git"

Log in to Hugging Face

We recommend logging in to Hugging Face before downloading models or datasets. Logging in provides higher Hugging Face Hub rate limits, even with a free account, and lets you download private or gated models and datasets your account can read. Public, ungated models can still be downloaded without logging in.

Run the following command in your terminal and follow the prompts. The hf command is included with huggingface_hub, a dependency of Sentence Transformers:

hf auth login

Alternatively, log in from Python or a notebook:

from huggingface_hub import login

login()

Sentence Transformers uses your saved credentials automatically by default, so you can continue loading models with the same code. To check your login, run hf auth whoami.

For servers, containers, or CI, provide a Hugging Face access token through the HF_TOKEN environment variable before starting Python. This takes precedence over a saved token.

A token with read access is sufficient for downloading models and datasets. Uploading models requires write access to the destination repository. Create tokens in your Hugging Face settings and see token permissions for details. For gated models, your account must also have been granted access to the model.

For more details, see the Hugging Face authentication guide.

Editable Install

If you want to make changes to sentence-transformers, you will need an editable install. Clone the repository and install it with these commands:

git clone https://github.com/huggingface/sentence-transformers
cd sentence-transformers
pip install -e ".[train,dev]"

These commands will link the new sentence-transformers folder and your Python library paths, such that this folder will be used when importing sentence-transformers.

Install PyTorch with CUDA support

To use a GPU/CUDA, you must install PyTorch with CUDA support. Follow PyTorch - Get Started for installation steps.