Install smolagents v1.24 (Hugging Face Agents): Real Setup Guide

So you ran pip install smolagents, copy-pasted an example from a blog post, and got ImportError: cannot import name 'HfApiModel'. Welcome to the most common question about Hugging Face agents right now: which install command actually works in 2026, and which tutorials are already stale?

This guide covers smolagents v1.24.0 – the current release as of January 2026 per the official releases page – with the exact pip extras you need, the install error nobody warns you about, and the sandbox setup that most tutorials skip entirely.

What smolagents actually is (and why deploy it locally)

smolagents is a library that lets you run agents in a few lines of code. The entire agent logic lives in roughly 1,000 lines in agents.py. Small enough to read on a long flight – which is also a reasonable way to understand what’s actually happening when your agent does something unexpected.

The headline feature is the CodeAgent – instead of emitting JSON tool calls, the LLM writes actual Python that calls your tools. There’s also a ToolCallingAgent that writes actions as JSON/text blobs for models that struggle with code generation. Pick whichever fits your model’s strengths.

System requirements (what you actually need)

Python 3.13 technically works but is where the install error in the next section lives. Python 3.10 and 3.12 are the tested targets.

The install command (and the trap)

The basic install is one line. The official installation docs list a dozen optional extras, and the one you pick changes everything about your dependency footprint.

# Most people should start here (adds DuckDuckGo, web search, etc.)
pip install "smolagents[toolkit]"

# Bare minimum - agents only, no built-in tools
pip install smolagents

# Want local model inference via transformers? DO THIS ORDER:
pip install "smolagents[torch]"
pip install "smolagents[transformers]"

That last bit is not paranoia. Running pip install smolagents[transformers] on macOS fails with error: metadata-generation-failed – the error is triggered when building the accelerate package. The fix: install smolagents[torch] first, then smolagents[transformers]. It’s logged as issue #940 and reproduces on fresh virtual environments with Python 3.13 on macOS Sequoia 15.3.1.

The full list of extras (as of v1.24.0 on PyPI): bedrock, blaxel, torch, audio, docker, e2b, gradio, litellm, mcp, mlx-lm, modal, openai, telemetry, toolkit, transformers, vision, vllm, all. [all] exists but pulls in every dependency – including the accelerate chain that breaks on macOS.

First-time configuration: the model

Here’s where copy-pasted tutorials break. Half the internet still imports HfApiModel. That class has been replaced by InferenceClientModel in current versions – HfApiModel only works with older smolagents installs, per the official HF announcement. Fresh install + old tutorial = immediate ImportError.

Working minimal config for v1.24.0:

from smolagents import CodeAgent, WebSearchTool, InferenceClientModel

model = InferenceClientModel() # defaults to Qwen/Qwen3-Next-80B-A3B-Thinking via HF Inference API
agent = CodeAgent(tools=[WebSearchTool()], model=model)
agent.run("What's the population of Reykjavik?")

The free Inference API works without a token, but you’ll hit rate limits fast in any real session. Set the HF_TOKEN environment variable – or pass it directly during initialization – to raise those limits with a PRO account.

Switching providers takes one extra argument. InferenceClientModel wraps huggingface_hub‘s InferenceClient and supports Cerebras, Cohere, Fal, Fireworks, HF-Inference, Hyperbolic, Nebius, Novita, Replicate, SambaNova, Together, and more (per the models reference docs):

# Route through Together AI instead
model = InferenceClientModel(
 model_id="deepseek-ai/DeepSeek-R1",
 provider="together",
)

Verify it actually works

Two ways. The CLI is faster.

# Check version
python -c "import smolagents; print(smolagents.__version__)"

# Smoke test via the bundled CLI
smolagent "What is 12 factorial?" --model-type "InferenceClientModel"

The smolagent CLI runs a multi-step CodeAgent and accepts a direct prompt or launches an interactive setup wizard when called with no arguments. There’s also a webagent command for browser automation built on helium – both are installed automatically with the package.

About that sandbox (this is where most guides mislead you)

Run a CodeAgent and it works? The LLM just executed arbitrary Python directly on your machine. The default executor is called LocalPythonExecutor and the name sounds reassuring. It is not.

Straight from the docs: “The built-in LocalPythonExecutor is not a security sandbox. It applies some restrictions but can be bypassed and must not be used as a security boundary.” Read that twice before deploying anything with additional_authorized_imports set wide open.

For anything beyond a local prototype, switch the executor:

from smolagents import CodeAgent, InferenceClientModel

# E2B managed sandbox (sign up at e2b.dev, set E2B_API_KEY)
with CodeAgent(model=InferenceClientModel(), tools=[], executor_type="e2b") as agent:
 agent.run("Compute the 100th Fibonacci number")

Supported backends: E2B (managed cloud), Modal, Docker (self-hosted container), and a WebAssembly option via Pyodide and Deno’s secure runtime – per the secure code execution docs.

One catch buried deep in those same docs: the simple executor_type="e2b" / "docker" / "modal" approach doesn’t support multi-agent setups. Hard architectural limit. If you’re building a hierarchy of agents, you need the full-system sandbox approach instead – more setup, no way around it.

The NCC Group security analysis of CodeAgent deployments is direct: never rely on additional_authorized_imports as a shortcut for specific tool creation. Restrict imports tightly, or sandbox everything in a container or remote environment.

Common install errors and what fixes them

• ImportError: cannot import name 'HfApiModel' – you’re on a current version. Switch to InferenceClientModel. The constructor is nearly identical.
• error: metadata-generation-failed during accelerate build – install smolagents[torch] first, then smolagents[transformers]. Confirmed on macOS Sequoia + Python 3.13, issue #940.
• Agent runs but output is garbled / “Error in code parsing” – almost always a model compatibility issue. GPT-OSS 20B doesn’t produce proper code responses, and similar breakage is reported with several local Ollama models (GitHub issues #1860, #1251, #1694). Switch to a Qwen2.5-Coder or an instruction-tuned model known to work with code generation.
• 422 Unprocessable Entity from Inference API – usually rate-limiting or an unsupported model on the chosen provider. Add HF_TOKEN, or change the provider argument.

Upgrade and uninstall

Minor version upgrades are one command. One exception: anything importing HfApiModel from the pre-InferenceProvider era breaks on upgrade. Search-replace the class name, re-test your model_id, done.

# Upgrade in place
pip install --upgrade "smolagents[toolkit]"

# Full uninstall
pip uninstall smolagents
# Optionally clean cached HF models
rm -rf ~/.cache/huggingface

Docker and E2B sandboxes don’t automatically clean up if you skip the context manager pattern (with CodeAgent(...) as agent:). Orphaned containers accumulate quietly – something to watch on long-running dev machines.

Where to go from here

Wire up a real tool. The @tool decorator turns any typed Python function into something the agent can call – that’s where the actual payoff is. Start with one tool, watch the code the agent writes, then add the next one.

FAQ

Do I need a Hugging Face account to use smolagents?

No. The free Inference API works without a token – just with stricter rate limits. Set HF_TOKEN when you start hitting them.

Can I run smolagents fully offline with a local model?

Yes – install with pip install "smolagents[transformers]" (after the torch-first trick above) and use TransformersModel, or point it at a local Ollama server through the LiteLLM integration. That said, some smaller open models produce outputs the parser can’t handle reliably – GPT-OSS 20B and certain Ollama models are documented failures (issues #1860, #1251, #1694). Test your model choice before building around it.

Is Docker or E2B better for production?

Depends on whether you want to own the infrastructure. E2B is managed – drop in executor_type="e2b", done. Docker means you control the image, the container limits, and the cleanup. For most teams shipping agents to users, the managed option wins on time-to-deploy. For regulated environments where data can’t leave your network, Docker (or a self-hosted sandbox) is the answer. Either way: remember neither approach supports multi-agent hierarchies out of the box.