Roboflow Docs

Upload Custom Model Weights

Roboflow offers the ability to upload model weights for your custom-trained models to your Roboflow projects for model deployment.

Uploading weights trained outside Roboflow

Once you've completed training your custom model, upload your model weights back to your Roboflow project to take advantage of Roboflow Inference.

To train a model in Roboflow, see Train a Model.

Model Support

Refer to the Supported Models table for details on weights upload compatibility.

Larger model sizes provide better training results. However, the larger the model size, the slower the training time, and inference (model prediction) speed. Consider whether you're looking for real-time inference on fast-moving objects or video feeds (better to use a smaller model), or you are processing data after it is collected, and more concerned with higher prediction accuracy (choose a larger model).

Versioned vs. Versionless Models Upload

Roboflow provides two distinct approaches for deploying models to your projects, each serving different use cases and organizational needs. The choice between versioned and versionless deployments depends on whether you need to track model evolution alongside dataset versions or want to share models across multiple projects in your workspace.

  • Versionless Deployments
    • Tied to the workspace level
    • Can be deployed to multiple projects simultaneously
    • Ideal for sharing models across different projects within the same workspace
  • Versioned Deployments
    • Tied to specific project versions
    • A Version can have multiple uploaded models
    • Ideal for tracking model evolution alongside dataset versions
    • Ideal for using model on Label Assist
    • Ideal for using model as checkpoint for training other models

Python SDK

First, make sure you have latest roboflow Python package installed:

pip install --update roboflow

Versionless Models

To upload versionless custom weights, use the workspace.deploy_model() method:

workspace.deploy_model(
    model_type="yolov8",  # Type of the model
    model_path="path/to/model",  # Path to model directory
    project_ids=["project1", "project2"],  # List of project IDs
    model_name="my-model",  # Name for the model (must have at least 1 letter, and accept numbers and dashes)
    filename="weights/best.pt"  # Path to weights file (default)
)

Parameters

ParameterTypeRequiredDescription
model_typestrYesType of model being deployed, e.g. yolov8, yolov11.
model_pathstrYesPath to the directory containing the model weights.
project_idslist[str]YesProject IDs to deploy the model to.
model_namestrYesName identifying the model. Must contain at least one letter; numbers and dashes allowed.
filenamestrNoWeights file name. Defaults to weights/best.pt.

Example

from roboflow import Roboflow

rf = Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace("YOUR_WORKSPACE")

workspace.deploy_model(
  model_type="yolov8",
  model_path="./runs/train/weights",
  project_ids=["project-1", "project-2", "project-3"],
  model_name="my-custom-model"
)

Versioned Models

The versioned custom-weights upload attaches each uploaded model to a dataset Version. If you do not have a version generated in your dataset, you can create one in-app or via the API.

See docs on how to load a version through the API or reference the example below.

To upload custom weights, use the version.deploy() method in the Python SDK.

Usage

version.deploy(
    model_type="yolov8",  # Type of the model
    model_path="path/to/model",  # Path to model directory
    filename="weights/best.pt"  # Path to weights file (default)
)

Parameters

ParameterTypeRequiredDescription
model_typestrYesType of model being deployed, e.g. yolov8, yolov11.
model_pathstrYesPath to the directory containing the model weights.
filenamestrNoWeights file name. Defaults to weights/best.pt.

Example

from roboflow import Roboflow

rf = Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace().project("PROJECT_ID")

#can specify weights_filename, default is "weights/best.pt"
version = project.version(VERSION_ID)

#example1 - directory path is "training1/model1.pt" for yolov8 model
version.deploy("yolov8", "training1", "model1.pt")

#example2 - directory path is "training1/weights/best.pt" for yolov8 model
version.deploy("yolov8", "training1")

Important Notes

A version can have multiple uploaded models. See Versions, Trainings, and Models for how models on a version are addressed.

CLI

Authentication

Before using any CLI commands, you need to authenticate with Roboflow:

  1. Run the authentication command: roboflow login
  2. Visit the URL shown in the terminal: https://app.roboflow.com/auth-cli
  3. Get your authentication token from the website
  4. Paste the token in your terminal

The credentials will be automatically saved to ~/.config/roboflow/config.json

Uploading Model Weights

The Roboflow CLI provides a command to upload trained model weights to your Roboflow projects. This is useful when you want to deploy custom-trained models to Roboflow.

Basic Usage

roboflow upload_model -w <workspace> -p <project> -t <model_type> -m <model_path> [-v <version>] [-f <filename>] [-n <model_name>]

Parameters

FlagRequiredDescription
-w, --workspaceNoWorkspace ID or URL. Defaults to your default workspace.
-p, --projectYesProject ID to upload into. Repeat the flag to upload a versionless model to multiple projects.
-t, --model_typeYesModel type, e.g. yolov8, paligemma2, rfdetr-medium.
-m, --model_pathYesPath to the directory containing the trained model file.
-v, --version_numberNoDataset version to attach the model to.
-f, --filenameNoModel file name. Defaults to weights/best.pt.
-n, --model_nameConditionalModel name. Required for versionless model deploys.

Examples

<pre class="language-bash" data-overflow="wrap"><code class="lang-bash"># 1. Upload a model to a specific version: <strong>roboflow upload_model -w my-workspace -p my-project -v 1 -t yolov8 -m ./weights </strong>

2. Upload a versionless model to multiple projects:

roboflow upload_model -w my-workspace -p project1 -p project2 -t yolov11 -n my-model-v1 -m ./weights

3. Upload a versionless RF-DETR medium model to a single project:

roboflow upload_model -w my-workspace -p my-project -t rfdetr-medium -n my-model-name -m ./ -f weights.pt </code></pre>

MCP Server

Connect your AI agent to the MCP Server and it can upload weights you trained elsewhere with these tools:

ToolDescription
models_upload_custom_weightsGet the recipe for uploading locally trained weights to Roboflow.

Next Steps

  1. Check out your model in the "Models" tab of Roboflow
  2. Run your model locally with Roboflow Inference Server.
  3. Review the deployment options.