Skip to main content
Learn how to package a handler function into a Docker image and deploy it as a Serverless worker on Runpod.

​
Requirements

To deploy a worker image, you need:

​
Project organization

Organize your project files in a directory structure like this:
Your requirements.txt file should list all Python packages your handler needs:

​
Creating a Dockerfile

The Dockerfile tells Docker how to build your worker image. Create a file named Dockerfile (no extension) in your project’s root directory:
This Dockerfile starts with a Python base image, installs your dependencies, copies your handler code, and specifies the command to run when the container starts.

​
Including models and external files

If your handler uses machine learning models or other external files, include them in the Docker image:
Always include your model files directly in the Docker image rather than downloading them at runtime to ensure faster startup times and more reliable execution.

​
Building the Docker image

From your terminal, navigate to your project directory and build the Docker image:
Replace [DOCKER_USERNAME] with your Docker Hub username, [WORKER_NAME] with a descriptive name for your worker, and v1.0.0 with an appropriate version tag.
The --platform linux/amd64 flag is required to ensure compatibility with Runpod’s infrastructure.

​
Testing your image locally

Before pushing it to the registry, you should test your Docker image locally:
If your handler is properly configured with a test input, you should see it process the test input and provide output.

​
Pushing the image to Docker Hub

Make your image available to Runpod by pushing it to Docker Hub:
Once your image is in the Docker container registry, you can create a Serverless endpoint through the Runpod console.

​
Image versioning

For production workloads, use SHA tags for absolute reproducibility:
Versioning best practices:
  • Never rely on the :latest tag for production.
  • Use semantic versioning AND SHA tags for clarity and reproducibility.
  • Document the specific image SHA in your deployment documentation.
  • Keep images as small as possible for faster startup times.

​
Troubleshooting deployment issues

If your worker fails to start or process requests:
  1. Check the logs in the Runpod console for error messages.
  2. Verify your handler function works correctly in local testing.
  3. Ensure all dependencies are properly installed in the Docker image.
  4. Check that your Docker image is compatible with the selected GPU type.
  5. Verify your input format matches what your handler expects.

​
Next steps

After successfully deploying your worker, you can: