Skip to main content
Version: 1.35

Repository requirements

Before linking your repository to Deeploy, ensure it meets the following requirements:

  1. Follows the repository contract
  2. Contains a folder named 'model' that includes one of the following files:
    • model.<extension>; your machine learning model object.
    • reference.json; a reference to your machine learning model
  3. (Optional) Contains a folder named 'explainer' that includes explainer.dill; an explainer object created using the dill library.

For more details on each requirement, consult the corresponding section of this article.


Repositories that don't adhere to the requirements will result in the failure of your Deployment

Repository contract

In order to successfully create a Deployment from a Repository, the git repository needs to adhere to a certain format. We call this format the contract.

|__ model
| |__ reference.json or model.<extension>
|__ explainer
|__ reference.json or explainer.<extension>

An example of the use of the contract, as seen in the Iris Proba example;

|_ model
|_ model.bst


It is possible to have multiple folders, each with their own contract to deploy multiple models from a single Repository.

Model folder

The model folder is mandatory and contains a (reference to a) machine learning model.

If you want to use a model file that holds your trained model, ensure compatibility and refer to the supported framework versions to determine the specific file type required for your chosen framework.


It is crucial that you have only one model file named model.extension (i.e. if you use my_model.<extension>, your Deployment will fail)

Alternatively, you can use the reference system

Explainer Folder

The explainer folder is optional and contains (a referenc to) an explainer.

To facilitate saving and loading explainers, we use the dill library. For supported frameworks, refer to supported framework versions.


It is crucial that you have only one explainer file named explainer.dill (i.e. if you use my_explainer.dill, your Deployment will fail)

Reference system and provenance

In situations where the size of individual files within a repository exceeds 100MB, or the total size surpasses 1GB, we strongly advise employing the referencing system. Using the reference system, the specific model is no longer stored in the git version history.

To uphold a consistent level of provenance, it is crucial to upload a new file to the blob and update your reference whenever you intend to deploy a new version. Avoid overwriting files within the blob system.

The reference system operates by replacing the contents of the ./model and ./explainer folders with a reference.json file, which serves as a reference to a folder stored in blob storage or a containerized model or explainer image. Deeploy currently offers support for AWS S3, Azure Blob Storage, and Google Cloud Storage (GCS).


It is crucial that you have only one reference file named reference.json (i.e. if you use my_reference.json, your Deployment will fail)

An example of the reference.json file, as seem in the Scikit-Learn census example;

"reference": {
"blob": {
"url": "s3://deeploy-examples/sklearn/census/20220801171658/model"

An example of the reference.json file that refers to a Docker image, as seen in the Custom Image Hello World Example

# this reference is used in example repository:
# ttps://
"reference": {
"docker": {
"image": "deeployml/example-custom-image-hello-world:0.3.0"
"port": 8080