Deploy YOLOv5 + FastAPI with Custom Weights on Hugging Face Spaces (Step-by-Step)

#fastapi #yolov5 #huggingface

Have you ever looked at impressive ML app demos and wondered, “How on earth do people even manage to deploy such heavy projects?” Yeah, I’ve been there too…

Why HF Spaces?

When I set out to deploy my YOLOv5 + FastAPI app, I was simply looking for a straightforward platform where I could test and iterate quickly, without worrying about infrastructure or complex deployment pipelines. I tried platforms like Render, but their free tier couldn’t handle my large custom model weights. That’s when I came across Hugging Face Spaces. It turned out to be exactly what I needed — fast, free, and beginner-friendly. With support for Docker and generous limits (16 GB RAM, 30 min idle timeout), Spaces made deployment as easy as pushing code.

Step 1: Creating a Space

Go to https://huggingface.co/spaces. Here you will see a lot of spaces created by others and you can also search for a space by category. Make sure to create a new account if you don't have one then click on New Space button in the top right corner.

Once you click new space you'll be directed to a page like this-

Give a suitable name and description to your space and you can choose license too if your project uses any then you'll come across Select the Space SDK option for my case I went with Docker as I already had a Dockerfile ready then I selected Blank as Docker template as for the Space Hardware and leave the option for Space Hardware as it is. While using the free tier your space will be public.

Step 2: Pushing your files to your HF space

After creating your Space, Hugging Face provides clear step-by-step instructions to set it up — including sample templates like Dockerfile, requirements.txt, and app.py. While you can manually upload files through the web UI, using Git makes the process much smoother and keeps your workflow version-controlled.

Before pushing your code to Hugging Face Spaces, there are a few important details to get right to ensure your deployment works smoothly.

First, your project directory must contain a README.md file — this isn’t just for documentation, it’s required by HF Spaces to properly render your app’s landing page. Include a short description of what your app does and any helpful usage notes. If your project doesn't contain a README.md file with the following details, you'll most probably run into Configuration Error

---
title: "Your App Title"
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
---

# Your App Title

A brief description of what your app does.

Second, since Spaces run in a restricted environment, you won’t have write access to arbitrary directories like /.cache or /uploads. Always use the /tmp directory for saving temporary files, such as image uploads or processed outputs.

Third, avoid using torch.load() directly on models trained with YOLOv5 — it often fails when dependencies like custom modules are missing. Instead, prefer loading the model using torch.hub or the ultralytics.YOLO interface for better compatibility. Something like this-

model = torch.hub.load('ultralytics/yolov5', 'custom', path='best.pt', trust_repo=True)

Finally, make sure your FastAPI app runs on port 7860. Hugging Face expects this specific port for Spaces to detect and serve your app correctly. You can do this by setting:

uvicorn.run(app, host="0.0.0.0", port=7860)

Will all this changes you can start with pushing your code to your HF space. In my case, I already had the code in a local Git repository that was also connected to GitHub. I didn’t want to disturb my existing GitHub remote, so I added Hugging Face as a second remote to the same repository.

Here’s how I did it:

First, initialize Git if your project isn’t already a Git repo:

git init

Then add Hugging Face as a new remote (replace <your-space-name> with your actual Space name):

git remote add hf https://huggingface.co/spaces/<your-username>/<your-space-name>

Now commit your files:

git add .
git commit -m "Initial commit for HF Space"

Push to Hugging Face:

git push hf main

Before pushing your code, make sure to handle large files like best.pt properly. Hugging Face Spaces has a file size limit for regular Git pushes, so you'll either need to use Git LFS (Large File Storage) or manually upload the large files via the Hugging Face Space's GUI by clicking on the Contribute button under the Files tab

That’s it — once pushed, Hugging Face Spaces automatically starts building your app based on the Dockerfile and displays logs in real time.

Once the deployment is successful, your FastAPI app will be accessible at:

https://<username>-<space_name>.hf.space/

If you found this blog helpful, feel free to leave a ❤️ and drop your thoughts or questions in the comments. I'd love to hear your feedback and help if you get stuck anywhere!