How to publish a Sentence Transformers model to Hugging Face Hub

A trained Sentence Transformers model becomes easier to reuse when the saved model directory is published to a Hugging Face Hub repository. Publishing the model gives teammates, deployment jobs, and evaluation scripts one stable repo ID instead of a local path that only exists on one machine.

SentenceTransformer.push_to_hub() uploads the model files, creates the repository when it is missing, and returns the commit URL for the upload. Passing a write-scoped token directly to the method keeps the publish script independent of the machine's stored Hugging Face login state.

Keep the first upload private until the model card, license, and reload smoke test look right. Reloading the model from the Hub before handing out the repo ID catches missing files, wrong repository ownership, and private-repo token problems while the change is still easy to fix.

1. Choose the local model directory and target Hub repository ID.

   Local model: support-embeddings
   Hub repository: acme-search/support-embeddings
   Visibility: private

   The repository ID must include the user or organization that will own the model. Keep the local directory focused on one saved model so the upload does not include training logs, notebooks, or unrelated checkpoints.

2. Make a write-scoped Hugging Face token available as HF_TOKEN for the current shell or CI job.

   Do not paste a real token into the publish script, terminal history, screenshots, or article text. Use a secret manager or a non-echoing prompt for interactive shells.

3. Check which Hub account the token will publish as.

   $ python - <<'PY'
   import os
   from huggingface_hub import whoami
   
   account = whoami(token=os.environ["HF_TOKEN"])
   print(account["name"])
   PY
   acme-search

4. Reload the local model before uploading it.

   $ python - <<'PY'
   from sentence_transformers import SentenceTransformer
   
   model = SentenceTransformer("support-embeddings")
   embeddings = model.encode(
       ["reset password", "change billing address"],
       show_progress_bar=False,
   )
   
   print("local model: support-embeddings")
   print(f"embedding shape: {embeddings.shape}")
   PY
   local model: support-embeddings
   embedding shape: (2, 384)

   The shape should match the number of smoke-test texts and the embedding dimension produced by the saved model.

5. Create the publish script beside the saved model directory.

   publish_sentence_model.py

   import os
    
   from sentence_transformers import SentenceTransformer
    
    
   repo_id = "acme-search/support-embeddings"
   local_model_path = "support-embeddings"
    
   model = SentenceTransformer(local_model_path)
   commit_url = model.push_to_hub(
       repo_id=repo_id,
       token=os.environ["HF_TOKEN"],
       private=True,
       safe_serialization=True,
       local_model_path=local_model_path,
       exist_ok=True,
       replace_model_card=False,
       commit_message="Publish support embeddings model",
   )
    
   print(f"published model: {repo_id}")
   print(f"commit: {commit_url}")

   safe_serialization=True keeps the uploaded weights in .safetensors format. replace_model_card=False avoids overwriting a model card that was edited in the Hub UI during a rerun.

6. Run the publish script.

   $ python publish_sentence_model.py
   published model: acme-search/support-embeddings
   commit: https://huggingface.co/acme-search/support-embeddings/commit/4f9d4b3d7ac8e1d7b6f23c9a0e4d89c5a71b2e46

   exist_ok=True lets a rerun update the same repository instead of failing when the repository already exists.

7. Create a Hub reload smoke test.

   verify_published_model.py

   import os
    
   from sentence_transformers import SentenceTransformer
    
    
   repo_id = "acme-search/support-embeddings"
    
   model = SentenceTransformer(repo_id, token=os.environ["HF_TOKEN"])
   embeddings = model.encode(
       ["reset password", "change billing address"],
       show_progress_bar=False,
   )
    
   print(f"repo: {repo_id}")
   print(f"embedding shape: {embeddings.shape}")

   Private repositories need the token for reloads. Public repositories can omit the token argument after the model is published.

8. Run the Hub reload smoke test.

   $ python verify_published_model.py
   repo: acme-search/support-embeddings
   embedding shape: (2, 384)

9. Remove the temporary publish and verification scripts.

   $ rm publish_sentence_model.py verify_published_model.py

10. Remove the token from the current shell after publishing.

    $ unset HF_TOKEN