Getting started

Install TorchServe and torch-model-archiver

  1. Install dependencies

    Note: For Conda, Python >=3.8 is required to run Torchserve.

For Debian Based Systems/ MacOS

  • For CPU

    python ./ts_scripts/
  • For GPU with Cuda 12.1. Options are cu92, cu101, cu102, cu111, cu113, cu116, cu117, cu118, cu121

    python ./ts_scripts/ --cuda=cu121

Note: PyTorch 1.9+ will not support cu92 and cu101. So TorchServe only supports cu92 and cu101 up to PyTorch 1.8.1.

For Windows

Refer to the documentation here.

  • Install torchserve, torch-model-archiver and torch-workflow-archiver

    For Conda Note: Conda packages are not supported for Windows. Refer to the documentation here.

    conda install torchserve torch-model-archiver torch-workflow-archiver -c pytorch

    For Pip

    pip install torchserve torch-model-archiver torch-workflow-archiver
  • Now you are ready to package and serve models with TorchServe.

    Serve a model

    This section shows a simple example of serving a model with TorchServe. To complete this example, you must have already installed TorchServe and the model archiver.

    To run this example, clone the TorchServe repository:

    git clone

    Then run the following steps from the parent directory of the root of the repository. For example, if you cloned the repository into /home/my_path/serve, run the steps from /home/my_path.

    Store a Model

    To serve a model with TorchServe, first archive the model as a MAR file. You can use the model archiver to package a model. You can also create model stores to store your archived models.

    1. Create a directory to store your models.

      mkdir model_store
    2. Download a trained model.

    3. Archive the model by using the model archiver. The extra-files param uses a file from the TorchServe repo, so update the path if necessary.

      torch-model-archiver --model-name densenet161 --version 1.0 --model-file ./serve/examples/image_classifier/densenet_161/ --serialized-file densenet161-8d451a50.pth --export-path model_store --extra-files ./serve/examples/image_classifier/index_to_name.json --handler image_classifier

    For more information about the model archiver, see Torch Model archiver for TorchServe

    Start TorchServe to serve the model

    After you archive and store the model, use the torchserve command to serve the model.

    torchserve --start --ncs --model-store model_store --models densenet161.mar

    After you execute the torchserve command above, TorchServe runs on your host, listening for inference requests.

    Note: If you specify model(s) when you run TorchServe, it automatically scales backend workers to the number equal to available vCPUs (if you run on a CPU instance) or to the number of available GPUs (if you run on a GPU instance). In case of powerful hosts with a lot of compute resources (vCPUs or GPUs), this start up and autoscaling process might take considerable time. If you want to minimize TorchServe start up time you should avoid registering and scaling the model during start up time and move that to a later point by using corresponding Management API, which allows finer grain control of the resources that are allocated for any particular model).

    Get predictions from a model

    To test the model server, send a request to the server’s predictions API. TorchServe supports all inference and management apis through both gRPC and HTTP/REST.

    Using GRPC APIs through python client

    • Install grpc python dependencies :

    pip install -U grpcio protobuf grpcio-tools
    • Generate inference client using proto files

    python -m grpc_tools.protoc --proto_path=frontend/server/src/main/resources/proto/ --python_out=ts_scripts --grpc_python_out=ts_scripts frontend/server/src/main/resources/proto/inference.proto frontend/server/src/main/resources/proto/management.proto
    python ts_scripts/ infer densenet161 examples/image_classifier/kitten.jpg

    Using REST APIs

    As an example we’ll download the below cute kitten with


    curl -O

    And then call the prediction endpoint

    curl -T kitten_small.jpg

    Which will return the following JSON object

        "tiger_cat": 0.46933549642562866
        "tabby": 0.4633878469467163
        "Egyptian_cat": 0.06456148624420166
        "lynx": 0.0012828214094042778
        "plastic_bag": 0.00023323034110944718

    All interactions with the endpoint will be logged in the logs/ directory, so make sure to check it out!

    Now you’ve seen how easy it can be to serve a deep learning model with TorchServe! Would you like to know more?

    Stop TorchServe

    To stop the currently running TorchServe instance, run:

    torchserve --stop

    Inspect the logs

    All the logs you’ve seen as output to stdout related to model registration, management, inference are recorded in the /logs folder.

    High level performance data like Throughput or Percentile Precision can be generated with Benchmark and visualized in a report.

    Debugging Handler Code

    If you want to debug your handler code, you can run TorchServe with just the backend and hence use any python debugger. You can refer to an example defined here


    If you plan to develop with TorchServe and change some source code, follow the contributing guide.


    Access comprehensive developer documentation for PyTorch

    View Docs


    Get in-depth tutorials for beginners and advanced developers

    View Tutorials


    Find development resources and get your questions answered

    View Resources