Ollama: Ollama Installation and Environment Configuration
Installing Ollama is like giving your computer a local brain — one command, all platforms, ready out of the box.
⚠️ Note: Setting
OLLAMA_HOST=0.0.0.0:11434 exposes the Ollama service to all network interfaces, meaning anyone on the same network can call your AI Model. This is convenient for LAN access in development, but poses serious security risks if you have a public IP or no firewall configured. In production, always add authentication via an Nginx reverse proxy.
📋 Prerequisites: You need to master the following first
1. What You Will Learn
- One-click installation methods for three platforms
- System hardware requirements and compatibility checks
- Service startup and port configuration
- Custom paths via environment variables
- Common installation troubleshooting
2. A Real Story from a SaaS Founder
(1) The Pain Point: Environment Configuration Nightmare
Alice founded the GlobalShop e-commerce platform and needed to deploy AI-powered customer service on the company's Linux servers and her own Mac laptop. She tried llama.cpp — compiling CUDA, configuring environments, resolving dependency conflicts — spending two full days. Switching to another machine meant starting over.
(2) The Solution: One Command Does It All
Ollama packages compilation, dependencies, and Model management together. Alice only needs one command to install, completing cross-platform Deployment in ten minutes.
BASH
# macOS / Linux: one-line install
curl -fsSL https://ollama.com/install.sh | sh
# Verify installation
ollama --version
# ollama version is 0.5.x
3. System Requirements and Compatibility
(1) Minimum and Recommended Configuration
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores x86_64 / ARM64 | 8 cores+ |
| RAM | 8 GB (3B Model) | 32 GB (8B+ Model) |
| GPU | None (CPU Inference) | NVIDIA 8GB+ VRAM |
| Disk | 10 GB free space | 50 GB+ SSD |
| OS | macOS 13+ / Ubuntu 20.04+ / Windows 10+ | Latest LTS version |
(2) GPU Acceleration Support Matrix
| GPU Vendor | Platform | Support Method | Auto Detection |
|---|---|---|---|
| NVIDIA | Linux / Windows WSL2 | CUDA | ✅ Automatic |
| AMD | Linux | ROCm | ✅ Automatic |
| Apple | macOS | Metal | ✅ Automatic |
| Intel | Linux | SYCL | ⚠️ Experimental |
💡 Tip: Ollama automatically detects GPUs at startup. No manual driver path configuration needed — just install CUDA/ROCm and you're set.
▶ Example 1: Check System Compatibility (Linux)
BASH
# Check CPU architecture
uname -m
# Expected: x86_64 or aarch64
# Check available RAM in GB
free -g | awk '/^Mem:/{print $2}'
# Check NVIDIA GPU
nvidia-smi --query-gpu=name,memory.total --format=csv
# Check disk space
df -h / | awk 'NR==2{print $4}'
Output:
TEXT
# Command executed successfully
4. Three-Platform Installation Methods
(1) macOS Installation
flowchart LR
A[Download DMG] --> B[Drag to Applications]
B --> C[Launch Ollama]
C --> D[Auto-start Server]
D --> E[Verify: ollama --version]
| Method | Command | Notes |
|---|---|---|
| Official installer | Download DMG from ollama.com | Recommended, includes GUI menu bar |
| Homebrew | brew install ollama | For CLI enthusiasts |
| Manual start | ollama serve | Start service after installation |
▶ Example 2: macOS Complete Installation
BASH
# Option A: Homebrew install
brew install ollama
# Start the server
ollama serve
# Option B: Verify GUI app is running
ps aux | grep ollama
# Quick test
ollama run llama3.2 "Say hello in one sentence"
Output:
TEXT
I'm a helpful AI assistant running locally on your machine...
(2) Linux Installation
| Method | Command | Use Case |
|---|---|---|
| Official script | curl -fsSL https://ollama.com/install.sh | sh | Recommended, auto-detects GPU |
| Manual download | Download tar.gz from ollama.com | Offline environments |
| systemd | Auto-registered as systemd service | Long-running server |
▶ Example 3: Linux Installation and Service Management
BASH
# Install with official script (auto-detects GPU)
curl -fsSL https://ollama.com/install.sh | sh
# Check systemd service status
sudo systemctl status ollama
# Start/stop/restart service
sudo systemctl start ollama
sudo systemctl stop ollama
sudo systemctl restart ollama
# Enable auto-start on boot
sudo systemctl enable ollama
Output:
TEXT
# Command executed successfully
(3) Windows Installation
| Method | Command | Notes |
|---|---|---|
| Official installer | Download exe from ollama.com | Recommended, includes system tray |
| winget | winget install Ollama.Ollama | CLI installation |
| WSL2 | Install using Linux method inside WSL2 | Requires GPU passthrough |
▶ Example 4: Windows Installation and WSL2 GPU Verification
POWERSHELL
# Install via winget
winget install Ollama.Ollama
# Verify installation
ollama --version
# If using WSL2 with NVIDIA GPU, verify inside WSL
wsl
nvidia-smi # Should show GPU inside WSL
ollama run llama3.2 "Hello"
Output:
TEXT
// Execution successful
5. Environment Variables and Port Configuration
💡 Tip: When downloading multiple Models, Model files consume significant disk space (8B Model ~5GB, 70B Model ~40GB). You can use the
OLLAMA_MODELS environment variable to point the Model storage path to a larger disk partition (e.g., /data/ollama/models), preventing system disk space exhaustion. This is especially important in multi-Model Deployment scenarios.
ℹ️ Info:
OLLAMA_KEEP_ALIVE controls how long a Model stays in memory, defaulting to 5 minutes. For frequent usage, set it to 30m or longer to avoid reloading the Model on every request (cold start takes 5-30 seconds).
(1) Core Environment Variables
| Variable | Default | Purpose |
|---|---|---|
| OLLAMA_HOST | 127.0.0.1:11434 | Service listen address and port |
| OLLAMA_MODELS | ~/.ollama/models | Model file storage path |
| OLLAMA_KEEP_ALIVE | 5m | Model memory retention time |
| OLLAMA_NUM_PARALLEL | 1 | Number of parallel requests |
| OLLAMA_MAX_LOADED_MODELS | 1 | Maximum simultaneously loaded Models |
| OLLAMA_DEBUG | false | Debug log toggle |
(2) Listen Address Security Comparison
| Configuration | Security | Use Case |
|---|---|---|
| 127.0.0.1:11434 | ✅ Local access only | Development environment |
| 0.0.0.0:11434 | ⚠️ Accessible from all networks | Internal network service, requires firewall |
| 0.0.0.0:11434 + Nginx | ✅ Reverse proxy + authentication | Production environment |
⚠️ Note: After binding to
0.0.0.0, you must configure a firewall or reverse proxy, otherwise anyone can access your Ollama service.
▶ Example 5: Custom Environment Variable Configuration
BASH
# Linux/macOS: set environment variables
# Edit systemd service (Linux)
sudo systemctl edit ollama
# Add in the override file:
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_MODELS=/data/ollama/models"
Environment="OLLAMA_KEEP_ALIVE=30m"
# Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart ollama
# macOS: set via launchctl or shell profile
export OLLAMA_HOST=0.0.0.0:11434
ollama serve
Output:
TEXT
NAME ID SIZE
llama3.2:latest a80... 2.0 GB
mistral:latest 61... 4.1 GB
6. Common Installation Troubleshooting
(1) Quick Troubleshooting Table
| Symptom | Cause | Solution |
|---|---|---|
| "connection refused" | Service not started | ollama serve or restart systemd |
| "bind: address already in use" | Port conflict | lsof -i :11434 to find occupying process |
| "could not find GPU" | Driver not installed | Install NVIDIA CUDA / AMD ROCm |
| "out of memory" | Insufficient VRAM | Use a smaller Model or Quantized version |
| "permission denied" | Insufficient permissions | Check Linux user groups / directory permissions |
| "model not found" | Model not pulled | ollama pull <model> |
▶ Example 6: Port Conflict Diagnosis
BASH
# Check what process is using port 11434
lsof -i :11434
# or on Linux
ss -tlnp | grep 11434
# Kill the conflicting process if needed
kill -9 `<PID>`
# Or change Ollama port
export OLLAMA_HOST=127.0.0.1:8080
ollama serve
Output:
TEXT
NAME ID SIZE
llama3.2:latest a80... 2.0 GB
mistral:latest 61... 4.1 GB
7. Comprehensive Example: Fresh Server Deployment Script
⚠️ Warning: The
OLLAMA_HOST=0.0.0.0:11434 in the Deployment script is suitable for server internal network environments. If the server has a public IP, be sure to configure a firewall (ufw/iptables) to restrict external access to port 11434, or add authentication through an Nginx reverse proxy.
BASH
#!/bin/bash
# ============================================
# Comprehensive: Fresh server Ollama deployment
# Checks hardware, installs Ollama, verifies service
# ============================================
set -e
echo "=== Step 1: Hardware Check ==="
echo "CPU: $(nproc) cores"
echo "RAM: $(free -g | awk '/^Mem:/{print $2}')GB"
if command -v nvidia-smi &> /dev/null; then
echo "GPU: $(nvidia-smi --query-gpu=name --format=csv,noheader)"
echo "VRAM: $(nvidia-smi --query-gpu=memory.total --format=csv,noheader)"
else
echo "GPU: Not detected (CPU-only mode)"
fi
echo "Disk: $(df -h / | awk 'NR==2{print $4}') available"
echo ""
echo "=== Step 2: Install Ollama ==="
curl -fsSL https://ollama.com/install.sh | sh
echo ""
echo "=== Step 3: Configure Environment ==="
sudo mkdir -p /data/ollama/models
sudo systemctl edit ollama <<EOF
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_MODELS=/data/ollama/models"
Environment="OLLAMA_KEEP_ALIVE=30m"
EOF
sudo systemctl daemon-reload
sudo systemctl restart ollama
echo ""
echo "=== Step 4: Verify Service ==="
sleep 3
if curl -s http://localhost:11434/api/tags > /dev/null; then
echo "SUCCESS: Ollama is running on port 11434"
ollama --version
else
echo "FAILED: Check logs with: journalctl -u ollama"
fi
echo ""
echo "=== Step 5: Pull First Model ==="
ollama pull llama3.2
echo "Deployment complete! Run: ollama run llama3.2"
❓ FAQ
Q The
ollama command is not found after installation, what should I do?A On Linux, check if
/usr/local/bin is in your PATH. On macOS after installing via Homebrew, run brew link ollama. On Windows, restart the terminal.Q Docker installation or direct installation — which should I choose?
A Choose direct installation for local development (simpler). Choose Docker for server Deployment (easier isolation and ops). This lesson covers direct installation; Docker is detailed in Lesson 15.
Q How do I configure GPU Inference in WSL2?
A After installing NVIDIA CUDA on Windows, WSL2 automatically inherits the GPU. Run
nvidia-smi in WSL2 to verify — if you see the GPU, it's ready. No need to install CUDA separately inside WSL2.Q How do I set Ollama to auto-start on boot?
A The Linux install script auto-registers a systemd service and enables boot auto-start. macOS adds the app to login items automatically after installation. Windows adds it to startup items.
Q Where are Model files stored by default? Can I change the path?
A Default is
~/.ollama/models. Set the OLLAMA_MODELS environment variable to change it — useful when disk space is low and you need to mount external storage.Q How can I confirm GPU acceleration is working?
A Run
ollama run --verbose <model> and check the logs. Messages like using CUDA or using Metal indicate GPU acceleration is enabled. You can also use nvidia-smi to observe VRAM usage during Inference.📖 Summary
- Ollama supports one-click installation on macOS / Linux / Windows
- Minimum 8GB RAM for 3B Models, recommended 16GB+ for 8B Models
- Default listen on 127.0.0.1:11434, changeable via OLLAMA_HOST
- OLLAMA_MODELS environment variable allows custom Model storage path
- GPU acceleration is auto-detected: NVIDIA CUDA / AMD ROCm / Apple Metal
- Common issues can be quickly diagnosed through port checks and log inspection
📝 Exercises
- Basic (Difficulty ⭐): Install Ollama on your current system and run
ollama --versionto confirm success. - Intermediate (Difficulty ⭐⭐): Configure
OLLAMA_HOSTandOLLAMA_MODELSenvironment variables to bind the service to0.0.0.0:11434and store Models in a custom path, then verify the configuration takes effect. - Advanced (Difficulty ⭐⭐⭐): Write an automated Deployment script that covers hardware detection, Ollama installation, environment configuration, and Model pulling, outputting a Deployment report.