> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/models/model-weights/upload-custom-weights.md).

# Upload Custom Model Weights

## 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](https://inference.roboflow.com/).

To train a model in Roboflow, see [Models](/models/readme.md).

### Model Support

Refer to the [Supported Models table](/models/supported-models.md) for details on weights upload compatibility.

{% hint style="warning" %}

* YOLOv8 models must be trained on `ultralytics==8.0.196`
* YOLOv9 models must be trained and uploaded using `ultralytics` from <https://github.com/WongKinYiu/yolov9>
* YOLOv10 models must be trained and uploaded using `ultralytics` from

  <https://github.com/THU-MIG/yolov10>
* YOLOv11 models must be trained on `ultralytics<=8.3.40`
* YOLOv12 models must be trained and uploaded using `ultralytics` from <https://github.com/sunsmarterjie/yolov12>
  {% endhint %}

{% hint style="info" %}
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).
{% endhint %}

### 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](/models/versions-trainings-and-models.md) 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

### Upload Custom Weights

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

```bash
pip install --update roboflow
```

{% tabs %}
{% tab title="Python SDK (Versionless)" %}
To upload versionless custom weights, use the `workspace.deploy_model()` method:

```python
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**

| Parameter     | Type       | Required | Description                                                                               |
| ------------- | ---------- | -------- | ----------------------------------------------------------------------------------------- |
| `model_type`  | str        | Yes      | Type of model being deployed, e.g. `yolov8`, `yolov11`.                                   |
| `model_path`  | str        | Yes      | Path to the directory containing the model weights.                                       |
| `project_ids` | list\[str] | Yes      | Project IDs to deploy the model to.                                                       |
| `model_name`  | str        | Yes      | Name identifying the model. Must contain at least one letter; numbers and dashes allowed. |
| `filename`    | str        | No       | Weights file name. Defaults to `weights/best.pt`.                                         |

**Example**

```python
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"
)
```

{% endtab %}

{% tab title="Python SDK (Versioned)" %}
{% hint style="info" %}
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](https://docs.roboflow.com/datasets/versions/dataset-versions/create-a-dataset-version) or via the [API](https://docs.roboflow.com/datasets/versions/dataset-versions/create-a-dataset-version#python-sdk).

See docs on [how to load a version through the API](https://docs.roboflow.com/datasets/versions/dataset-versions#view-a-version) or reference the example below.
{% endhint %}

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

**Usage**

```python
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**

| Parameter    | Type | Required | Description                                             |
| ------------ | ---- | -------- | ------------------------------------------------------- |
| `model_type` | str  | Yes      | Type of model being deployed, e.g. `yolov8`, `yolov11`. |
| `model_path` | str  | Yes      | Path to the directory containing the model weights.     |
| `filename`   | str  | No       | Weights file name. Defaults to `weights/best.pt`.       |

**Example**

```python
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**

{% hint style="info" %}
A version can have multiple uploaded models. See [Versions, Trainings, and Models](/models/versions-trainings-and-models.md) for how models on a version are addressed.
{% endhint %}
{% endtab %}

{% tab title="CLI (Versionless and versioned)" %}
**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**

{% code overflow="wrap" %}

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

{% endcode %}

**Parameters**

| Flag                   | Required    | Description                                                                                    |
| ---------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `-w, --workspace`      | No          | Workspace ID or URL. Defaults to your default workspace.                                       |
| `-p, --project`        | Yes         | Project ID to upload into. Repeat the flag to upload a versionless model to multiple projects. |
| `-t, --model_type`     | Yes         | Model type, e.g. `yolov8`, `paligemma2`, `rfdetr-medium`.                                      |
| `-m, --model_path`     | Yes         | Path to the directory containing the trained model file.                                       |
| `-v, --version_number` | No          | Dataset version to attach the model to.                                                        |
| `-f, --filename`       | No          | Model file name. Defaults to `weights/best.pt`.                                                |
| `-n, --model_name`     | Conditional | Model 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>

{% endtab %}
{% endtabs %}

## Next Steps

1. Check out your model in the "Models" tab of Roboflow
2. Run your model locally with [Roboflow Inference Server](https://inference.roboflow.com/).
3. [Deploy your model](/models/readme.md)

## Python SDK

Roboflow can host model weights you trained outside the platform - locally with [Ultralytics](https://docs.ultralytics.com/), in a Sagemaker job, or in any framework that exports to PyTorch / ONNX. Once uploaded, the model is reachable through every Roboflow inference path: the SDK's `model.predict()`, the REST API, hosted Workflows, and Dedicated Deployments.

The SDK exposes two equivalent paths:

* `Workspace.deploy_model()` - for one-shot uploads against an arbitrary set of projects.
* `Version.deploy()` - for attaching weights to a specific dataset version.

### Upload weights to a version

Use `Version.deploy()` when the weights correspond to a specific Roboflow dataset version (recommended - keeps the dataset → weights → inference URL chain coherent).

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
version = rf.workspace().project("my-detector").version(3)

version.deploy(
    model_type="yolov8",                  # or yolov5, yolov11, rfdetr-nano, etc.
    model_path="./training-runs/exp42",    # directory containing weights/best.pt
    filename="weights/best.pt",            # optional, default
)
```

`model_path` is the run directory; `filename` is the path within that directory to the `.pt` weights file. The SDK uploads the weights and registers them against the version, after which `version.model.predict(...)` runs against the uploaded weights instead of any prior Roboflow-trained version.

### Upload weights to one or more projects

Use `Workspace.deploy_model()` when the weights aren't tied to a specific dataset version (e.g. an externally trained generalist model that you want to make available across several projects).

```python
ws = rf.workspace()

ws.deploy_model(
    model_type="yolov8",
    model_path="./generalist-run",
    project_ids=["my-detector", "my-classifier"],
    model_name="generalist-v3",
    filename="weights/best.pt",
)
```

#### Parameters

* `model_type` (str) - model architecture identifier. Pass an invalid value to get the full list back as an error.
* `model_path` (str) - directory containing the trained weights.
* `project_ids` (list\[str]) - projects to attach the model to.
* `model_name` (str) - name for the uploaded model in the web app.
* `filename` (str, default `"weights/best.pt"`) - path within `model_path` to the weights file.

### Where it ends up

After upload completes, the model is available:

* In the Roboflow web app under the project's **Versions → Deploy** tab.
* Through the SDK as `version.model.predict(...)`.
* Through the REST API at `https://serverless.roboflow.com/infer/...`.
* As a target for [Dedicated Deployments](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments#python-sdk).