Hugging Face in ten minutes: the cool stuff first

The big idea

Hugging Face is the place where most open AI models are published, the way GitHub is the place where most open source code lives. Its website, the Hubhuggingface.co: a hosting site of Git repositories for models, datasets and demo apps (Spaces), each with files, versions and discussions., hosts over 2 million models, 1.5 million datasets and 1.5 million demo apps, and a set of free libraries can pull any of them onto your machine in one line.

The usual way to learn it is backwards: accounts, tokens, libraries, then finally a result. This lesson does it the other way round, like a test drive before the manual. You will do five things, from zero effort upward, and each one ends with something working. Every command below was run for real on an ordinary laptop CPU, with no GPU, and the outputs shown are the ones it printed. After that, a short map explains what just happened.

How it works

The quick wins, ordered by how much you need to set up:

1. 1. Use a Space A live app on the Hub. Open it, type or upload, get a result. Nothing to install.
2. 2. Try the model page Many model pages have a widget or playground that runs the model on a hosted provider.
3. 3. Chat in a terminal Two Transformers commands download a small chat model and talk to it on your own machine.
4. 4. Three lines of Python pipeline() picks the right preprocessing and model for a task: sentiment, images, speech.
5. 5. A local chat app llama.cpp or Ollama run a compressed GGUF file straight from a Hub repo.

1. Use a Space (needs: a browser)

A SpaceA demo app hosted on the Hugging Face Hub, built with Gradio, Docker or static HTML, whose code lives in a Git repository like a model's. is a live app that someone built around a model: type a prompt, upload a photo or record your voice, and see the result. Go to huggingface.co/spaces, pick a category such as image generation, speech synthesis, OCR or chatbots, and open one. That is the whole step.

Many of the most interesting Spaces run on ZeroGPUHugging Face's shared GPU pool for Spaces. A GPU is attached only while a request runs, so one GPU serves many Spaces., a shared pool of large NVIDIA GPUs that Hugging Face attaches to a Space only while it is answering a request. The cards on the Spaces page show what each app runs on, for example "Running on Zero". Hugging Face keeps a curated list at huggingface.co/spaces/enzostvs/zero-gpu-spaces.

2. Try a model on its page (needs: a browser, an account, often credits)

Open a model page, for example huggingface.co/Qwen/Qwen2.5-0.5B-Instruct. Many pages have a small box where you type an input and see the model's output, and chat models can be compared side by side in the Inference Playground at huggingface.co/playground. These run on Inference ProvidersHugging Face's pay-per-use hosted inference: one API in front of many partner providers, used by model page widgets, the playground and code.: partner companies that host the model and bill per request through your Hugging Face account. How to read a model page shows how to read everything else on that page.

3. Chat in a terminal (needs: Python 3.10+ and transformers)

Now the model runs on your own machine. Transformers, Hugging Face's main Python library, has a built-in chat command. It talks to a small local server, so you start that first:

pip install "transformers[serving]"
transformers serve                              # terminal 1: a local server on port 8000
transformers chat Qwen/Qwen2.5-0.5B-Instruct     # terminal 2: chat with a 0.5B model

The chat window lists its commands (!help, !status, !clear, !exit), loads the model, and waits for you. We sent "Tell me a one-line joke about robots." and got:

Qwen/Qwen2.5-0.5B-Instruct is warm.

<Qwen/Qwen2.5-0.5B-Instruct>:
Why did the robot go to therapy? Because it was feeling blue!

We left out the speed line it prints after each answer, because our test machine was busy with other jobs. Type !exit to quit: we typed plain exit first, and the model politely answered it as a message.

The first run downloads the model, a single 988 MB model.safetensors file plus a few small tokenizer files. A 0.5-billion-parameter model is tiny by today's standards, which is exactly why it runs on a laptop CPU. Do not expect accurate facts from it; expect a working chat.

4. Three lines of Python (needs: transformers and PyTorch)

The pipelineThe Transformers function pipeline(task, model) that bundles preprocessing, the model and postprocessing, so one call goes from raw input (text, an image, audio) to a readable result. function is the shortest path from "a task" to "an answer". You name a task and a model from the Hub; it downloads the model, prepares the input, runs it and returns a readable result. Install once with pip install transformers torch.

Text: is this sentence positive or negative? The model is a 268 MB DistilBERT fine-tuned for sentiment.

from transformers import pipeline

classifier = pipeline(task="sentiment-analysis", model="distilbert/distilbert-base-uncased-finetuned-sst-2-english")
print(classifier(["I finally got this model running on my laptop!", "The download took forever."]))

[{'label': 'POSITIVE', 'score': 0.7150179743766785}, {'label': 'NEGATIVE', 'score': 0.9646170735359192}]

Images: what is in this photo? A 346 MB Vision Transformer trained on ImageNet's 1,000 classes looks at a photo of a cat from the Transformers docs:

from transformers import pipeline

classifier = pipeline(task="image-classification", model="google/vit-base-patch16-224")
url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
for guess in classifier(url, top_k=3):
    print(f"{guess['score']:.3f}  {guess['label']}")

0.434  lynx, catamount
0.035  cougar, puma, catamount, mountain lion, painter, panther, Felis concolor
0.032  snow leopard, ounce, Panthera uncia

Speech: write down what was said. Whisper ( Speech: ASR and TTS ) in its smallest English-only size, 151 MB, transcribes a short clip:

from transformers import pipeline

transcriber = pipeline(task="automatic-speech-recognition", model="openai/whisper-tiny.en")
print(transcriber("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac"))

{'text': ' I have a dream that one day, this nation will rise up, live out the true meaning of its creed.'}

Audio needs one extra program. On our first try, without it, the speech pipeline stopped with:

ValueError: ffmpeg was not found but is required to load audio files from filename

Install ffmpeg with your system's package manager (for example brew install ffmpeg on a Mac or sudo apt install ffmpeg on Ubuntu), and it works.

Two things to notice. First, the scores are confidences, not truth: the model is only 72 percent sure the first sentence is positive. Second, the same three lines work for every task; only the task name, the model id and the input change.

5. A local chat model from a GGUF file (needs: llama.cpp or Ollama)

The fastest way to chat with a language model on a laptop is a GGUFA single-file model format for llama.cpp and the apps built on it, holding the weights (usually quantized to fewer bits) plus metadata such as the chat template. file: a compressed copy of a model, with each weight stored in about 4 to 5 bits instead of 16 ( Quantization for inference explains how). Community members publish GGUF versions of popular models, and local apps can fetch them straight from the Hub.

With llama.cpp (the Hub docs install it with brew install llama.cpp; we used a prebuilt release), one command downloads a 398 MB file and opens a chat:

llama-cli -hf bartowski/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M

The part after the colon picks one of the repo's quantizations; Q4_K_M is a common default. llama-server with the same -hf argument starts an OpenAI-compatible server instead, which any app can call:

llama-server -hf bartowski/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M --port 8093
curl -s http://localhost:8093/v1/chat/completions -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"In one sentence, what is Hugging Face?"}],"max_tokens":60,"temperature":0}'

The answer, from the JSON it returned:

"content": "Hugging Face is a large language model platform that enables developers to build and deploy natural language processing (NLP) applications, including text generation, sentiment analysis, and more."

Fluent, confident and not quite right: Hugging Face is a hub for many kinds of models, not a language model platform. That is what to expect from a 0.5B model, and a good reason to judge models on your own examples.

With Ollama, the Hub docs give this form (we did not run it here). Enable Ollama in your Hub Local Apps settings to get the same command from any GGUF model page's "Use this model" menu:

ollama run hf.co/{username}/{repository}
ollama run hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF

Ollama uses the Q4_K_M file by default when the repo has one; add :{quantization} to the end to pick another.

What just happened

You used all three parts of Hugging Face without stopping to name them:

• The Hub stores Git repositories of three kinds: models, datasets and Spaces. A model repo holds weight files, a config, a tokenizer and a README called the model card. Every id you typed, like google/vit-base-patch16-224, is owner/name of one repo.
• Libraries and apps turn those files into something that runs. Transformers loaded the safetensors files for quick wins 3 and 4; llama.cpp loaded a GGUF file for quick win 5. Python downloads land in a cache folder (~/.cache/huggingface/hub by default), so the second run starts without downloading.
• Compute is wherever the math happens. Quick wins 3 to 5 ran on your own CPU. Spaces ran on Hugging Face's machines, and model page widgets ran on Inference Providers.

The rest of this module fills in that map. Next, how to read a model page before you download it. Then Can I run it? What a model needs works out which models fit your machine, Four ways to run a model compares hosted, local app, Python and browser routes, Accounts, tokens, downloads and datasets covers the account side, and Build and share your first Space ends with your own Space.

Try it

Match each thing you might want to do with the least you need to do it:

Then try these on your own machine:

1. In the sentiment example, replace the sentences with sarcasm, like "Great, another download." Does the model get the joke? What does the score tell you?
2. In the image example, use the URL of a photo of your own. Which of the top three guesses is right, and how confident was the model?
3. In the terminal chat, ask the 0.5B model a fact you know well. How often is it right?

Trade-offs

Common mistakes

• Calling pipeline(task=...) without a model. It works, but Transformers picks a default and warns "Using a pipeline without specifying a model name and revision in production is not recommended." Always name the model.
• Running transformers chat without the [serving] extra or without transformers serve running. The chat command talks to that local server.
• Forgetting ffmpeg, then reading the speech pipeline's error as a model problem.
• Judging a model family by its 0.5B size. Small models are for learning and simple tasks; their facts are unreliable.
• Expecting free hosted inference everywhere. Spaces have a free quota; Inference Providers bill per request.

In the wild

Hugging Face

Hugging Face Spaces (opens in a new tab)

The Spaces directory describes itself as a place to "discover amazing ML apps made by the community". You can filter it by category (image and video generation, speech synthesis, OCR, chatbots, background removal and many more) and browse weekly picks, and each app's card shows the hardware it runs on, such as ZeroGPU or a CPU. Because a public Space is a Git repository like a model, you can open its files to see exactly how it was built, which is where lesson 16.06 picks up.

Check yourself

Recap