Linux Mint 22.3 Cinnamon as a Lightweight Local AI Workstation: Python, GPU Acceleration (CUDA/ROCm Alternatives), and a Reproducible Tooling Stack

Introduction: What you’ll build (and why Mint 22.3 is a great base)

In this tutorial, you will turn Linux Mint 22.3 “Zena” (Cinnamon 6.6) into a reliable, lightweight workstation for local AI development. You will set up:

• A clean, reproducible Python stack (with pinned dependencies and isolated environments)
• GPU acceleration options: NVIDIA CUDA, AMD ROCm (where supported), and practical alternatives (OpenCL, Vulkan, CPU-optimized stacks) when ROCm/CUDA isn’t available
• A reproducible tooling workflow using uv (fast Python packaging), venv, and optional containers
• Verification steps so you can prove everything works (PyTorch/JAX/TensorFlow sanity checks)

Mint is valuable here because it aims to be stable, user-friendly, and lightweight—which makes it ideal for developers who want to spend time building models, not fighting their OS. The goal is a setup you can rebuild on a fresh machine (or after reinstalling) with minimal surprises.

Prerequisites

Hardware

• CPU: Any modern x86_64 CPU (more cores helps for preprocessing)
• RAM: 16 GB recommended (8 GB workable for small models; 32 GB+ for serious local LLM work)
• Disk: 50–200 GB free depending on datasets/models; NVMe strongly recommended
• GPU (optional but recommended):
  • NVIDIA: best-supported for CUDA
  • AMD: ROCm support is hardware/driver sensitive; alternatives provided below

OS

• Linux Mint 22.3 Cinnamon installed and updated. (Download Here)

Skills

• Basic terminal usage (copy/paste commands, reading error messages)

Important warnings

• WARNING: GPU driver installation can break your graphical login if done incorrectly. Create a system snapshot before changing drivers.
• WARNING: Do not remove core Mint/Ubuntu packages blindly (e.g., Python system packages). Keep system Python for the OS; install your dev Python stack in isolated environments.

Step 1: Update Mint and create a rollback snapshot (do this first)

Why: A predictable base system prevents dependency conflicts. A snapshot lets you revert instantly if GPU drivers or libraries cause issues.

1.1 Update packages

sudo apt update
sudo apt -y upgrade
sudo apt -y autoremove

1.2 Reboot

sudo reboot

1.3 Create a Timeshift snapshot

Mint typically ships with Timeshift integrated.

1. Open Menu → Administration → Timeshift
2. Select RSYNC (simplest and robust for most setups)
3. Create a snapshot named: pre-ai-stack

Expected result: Timeshift shows a snapshot you can restore if driver installation goes wrong.

Screenshot description: Timeshift window with a list of snapshots; highlight pre-ai-stack and the “Create” button.

Step 2: Install core developer tools (compiler, headers, Git, monitoring)

Why: Many Python AI packages include native code or require compilation (or at least system headers). You also want basic observability tools for CPU/GPU/RAM usage.

sudo apt install -y \
  build-essential \
  pkg-config \
  git \
  curl \
  wget \
  unzip \
  ca-certificates \
  software-properties-common \
  python3 \
  python3-venv \
  python3-pip \
  linux-headers-$(uname -r) \
  htop \
  nvtop \
  lm-sensors

Expected result: Running git --version and python3 --version works.

git --version
python3 --version

Note: nvtop may not show anything until GPU drivers are installed.

Step 3: Pick a reproducible Python workflow (recommended: uv + venv)

Why: System Python on Mint is used by OS tools. If you install AI packages globally, you risk breaking the system or creating version conflicts. A reproducible workflow means you can rebuild the same environment later.

3.1 Install uv (fast Python package manager)

Why uv: It’s fast, supports lockfiles, and simplifies reproducible installs.

curl -LsSf https://astral.sh/uv/install.sh | sh

Then ensure your shell can find it:

export PATH="$HOME/.local/bin:$PATH"
uv --version

Expected result: uv --version prints a version number.

3.2 Create a project directory and a virtual environment

mkdir -p ~/ai/mint-ai-stack
cd ~/ai/mint-ai-stack
python3 -m venv .venv
source .venv/bin/activate
python -V

Expected result: python -V shows a Python 3 version and your prompt may show (.venv).

3.3 Pin dependencies with a lockfile

Use a pyproject.toml so your environment is declarative.

cat > pyproject.toml <<'EOF'
[project]
name = "mint-ai-stack"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
  "numpy",
  "scipy",
  "pandas",
  "matplotlib",
  "jupyterlab",
  "ipykernel",
  "rich",
  "python-dotenv",
]
EOF

Now install and generate a lock:

uv pip install -r <(uv pip compile pyproject.toml -o -)
# Optional: write a lock file you can commit
uv pip compile pyproject.toml -o requirements.lock.txt
uv pip install -r requirements.lock.txt

Expected result: jupyter lab is installed in the venv and requirements.lock.txt exists.

Step 4: Add a “one-command” bootstrap script (make it reproducible)

Why: You want a new machine setup to be: clone repo → run one script → done. This reduces mistakes and ensures consistency across projects.

cat > bootstrap.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$PROJECT_DIR"

if [ ! -d .venv ]; then
  python3 -m venv .venv
fi

source .venv/bin/activate

export PATH="$HOME/.local/bin:$PATH"

if ! command -v uv >/dev/null 2>&1; then
  echo "uv not found. Install it first: curl -LsSf https://astral.sh/uv/install.sh | sh" 
  exit 1
fi

uv pip compile pyproject.toml -o requirements.lock.txt
uv pip install -r requirements.lock.txt

python -c "import numpy; print('numpy:', numpy.__version__)"
EOF

chmod +x bootstrap.sh

Expected result: Running ./bootstrap.sh reinstalls the environment predictably and prints a NumPy version.

Step 5: Install VS Code (or keep it lightweight with alternatives)

Why: AI development is faster when you have good linting, notebooks, and debugging.

5.1 Option A: Install VS Code (Microsoft build) via .deb

cd ~/Downloads
wget -O code.deb "https://code.visualstudio.com/sha/download?build=stable&os=linux-deb-x64"
sudo apt install -y ./code.deb

Expected result: code --version prints a version and VS Code launches from the menu.

5.2 Option B: Lightweight editor

• Install micro + ripgrep:

sudo apt install -y micro ripgrep

Step 6: Decide on GPU acceleration path (NVIDIA CUDA vs AMD ROCm vs alternatives)

Why: Your framework choice (PyTorch/JAX/TensorFlow) and performance depends heavily on GPU stack support. On Linux, NVIDIA CUDA is the most consistent for local AI. AMD ROCm can be excellent but is more hardware- and version-dependent. If neither is viable, you can still do plenty with CPU-optimized builds or alternative GPU APIs.

6.1 Identify your GPU

lspci | grep -E "VGA|3D"

Expected result: You see something like “NVIDIA …” or “AMD/ATI …”.

Step 7 (NVIDIA path): Install NVIDIA driver safely, then use CUDA-enabled PyTorch

Why: The driver is required for CUDA compute. On Mint, the safest approach is typically using Driver Manager / Ubuntu-compatible packages rather than random scripts.

7.1 Install NVIDIA driver using Mint tools (recommended)

1. Open Menu → Administration → Driver Manager
2. Select the recommended NVIDIA driver (proprietary)
3. Apply changes, then reboot

Expected result: After reboot, nvidia-smi works.

nvidia-smi

Example expected output: A table showing driver version, GPU name, and running processes.

Screenshot description: Driver Manager showing NVIDIA driver options with a “recommended” label selected.

7.2 Common NVIDIA driver errors

• Error: nvidia-smi: command not found
  • Fix: Driver not installed. Re-open Driver Manager and install the recommended proprietary driver.
• Error: Black screen after reboot
  • Fix: Use Timeshift from recovery/live USB to restore pre-ai-stack. Then try a different driver version in Driver Manager.

7.3 Install CUDA-enabled PyTorch in your venv

Why: PyTorch wheels often bundle CUDA runtime libraries for user-space. You still need the NVIDIA kernel driver, but you usually do not need a full system CUDA toolkit for most development.

cd ~/ai/mint-ai-stack
source .venv/bin/activate

# Install PyTorch (choose a CUDA build supported by your PyTorch release)
uv pip install torch torchvision torchaudio

Expected result: PyTorch imports successfully.

python - <<'PY'
import torch
print('torch:', torch.__version__)
print('cuda available:', torch.cuda.is_available())
if torch.cuda.is_available():
    print('gpu:', torch.cuda.get_device_name(0))
PY

Expected output:

• cuda available: True
• GPU name printed

If CUDA is false: you likely installed a CPU-only wheel or your driver isn’t working. Re-check nvidia-smi first.

Step 8 (AMD path): ROCm where supported, otherwise use practical alternatives

Why: ROCm can accelerate PyTorch/JAX on supported AMD GPUs, but compatibility varies widely by GPU generation and kernel/driver requirements. On a stable desktop like Mint, you may prefer a conservative approach: try ROCm only if your GPU is known-good; otherwise use CPU-optimized builds or alternative backends.

8.1 Check AMD GPU and kernel/driver situation

lspci | grep -E "VGA|3D"
uname -r

Expected result: You know the exact GPU model and kernel version.

8.2 ROCm installation approach (high level)

Instructional guidance:

• Prefer ROCm packages that match your Ubuntu base compatibility.
• Use a Timeshift snapshot before ROCm changes.
• After install, validate with tools like rocminfo and clinfo (if installed).

WARNING: ROCm can require specific kernel/driver combos. If you install mismatched components, you may end up with a non-working GPU compute stack. If you’re unsure your GPU is supported, skip to the alternatives below.

8.3 AMD alternatives if ROCm is not viable

• Use CPU-optimized PyTorch with AVX2/AVX-512 (still fast for many workflows).
• Use OpenCL for certain workloads (limited framework support, but useful for some tools).
• Use Vulkan-based inference backends for some LLM tools (varies by project).
• Use containers with a known-good stack if your host environment is hard to stabilize.

8.4 Install CPU PyTorch (works everywhere)

cd ~/ai/mint-ai-stack
source .venv/bin/activate
uv pip install torch torchvision torchaudio

Expected result: torch.cuda.is_available() may be false, but training/inference works on CPU.

Step 9: Add JAX (optional) and verify accelerator detection

Why: JAX is popular for research and can use CPU/GPU/TPU backends. Even if you’re CPU-only, JAX is useful for fast numerical code.

cd ~/ai/mint-ai-stack
source .venv/bin/activate
uv pip install jax jaxlib

Expected result:

python - <<'PY'
import jax
print('jax:', jax.__version__)
print('devices:', jax.devices())
PY

You should see at least one CPU device. If you later configure a supported GPU backend, you’ll see GPU devices listed.

Step 10: Add a reproducible “system dependencies” manifest

Why: Python lockfiles are not enough. Many AI builds depend on system libraries (e.g., compilers, headers). Capture them so you can re-provision a machine consistently.

10.1 Create apt-packages.txt

cat > apt-packages.txt <<'EOF'
build-essential
pkg-config
git
curl
wget
unzip
ca-certificates
python3
python3-venv
python3-pip
htop
nvtop
lm-sensors
EOF

10.2 Install from it

sudo apt update
xargs -a apt-packages.txt sudo apt install -y

Expected result: A fresh Mint machine can install the same baseline packages with one command.

Step 11: Configure Jupyter and kernels cleanly

Why: A common failure mode is launching Jupyter from the wrong Python, then “missing” packages. Register your venv as a kernel so notebooks always use the correct environment.

cd ~/ai/mint-ai-stack
source .venv/bin/activate
python -m ipykernel install --user --name mint-ai-stack --display-name "Python (mint-ai-stack)"

Run Jupyter:

jupyter lab

Expected result: Your browser opens JupyterLab. When creating a notebook, you can select Python (mint-ai-stack).

Screenshot description: JupyterLab launcher page showing available kernels; highlight “Python (mint-ai-stack)”.

Step 12: Create a simple GPU/CPU benchmark script (prove performance)

Why: You need a quick “health check” that verifies your stack after updates. This also helps debug whether you’re actually using the GPU.

cat > verify_torch.py <<'PY'
import time
import torch

print('torch:', torch.__version__)
print('cuda available:', torch.cuda.is_available())

device = 'cuda' if torch.cuda.is_available() else 'cpu'
print('device:', device)

# Simple matmul benchmark
n = 4096
x = torch.randn((n, n), device=device)
y = torch.randn((n, n), device=device)

# Warmup
for _ in range(3):
    z = x @ y
    if device == 'cuda':
        torch.cuda.synchronize()

start = time.time()
z = x @ y
if device == 'cuda':
    torch.cuda.synchronize()
end = time.time()

print('matmul seconds:', round(end - start, 4))
print('result checksum:', float(z[0, 0]))
PY

source .venv/bin/activate
python verify_torch.py

Expected result:

• On GPU: significantly lower matmul time than CPU
• On CPU: it runs successfully, just slower

Troubleshooting: Common issues and fixes

1) “pip installs succeed, but imports fail in Jupyter”

Cause: Jupyter is using a different Python environment.

Fix: Ensure you installed and selected the correct kernel:

source ~/ai/mint-ai-stack/.venv/bin/activate
python -m ipykernel install --user --name mint-ai-stack --display-name "Python (mint-ai-stack)"

Then switch kernel inside JupyterLab.

2) “torch.cuda.is_available() is False on NVIDIA”

Cause: Driver not working or you’re using a CPU-only stack.

Fix:

1. Verify driver first: nvidia-smi
2. Reinstall PyTorch inside the venv (and avoid mixing system pip with venv pip)

3) “No space left on device” during installs

Cause: Wheels, caches, and model files are large.

Fix:

• Check space: df -h
• Clear pip/uv caches carefully if needed.

WARNING: Don’t delete random directories in /usr or /lib. Only clear user caches.

4) “GLIBC / libstdc++ version errors”

Cause: Mixing binaries built for different bases (common when downloading random wheels or using incompatible repos).

Fix:

• Prefer official wheels and keep environments isolated.
• If you must use containers, do it consistently (see Next Steps).

Testing: Verify the workstation is actually ready for AI work

Run these checks in order.

1) System sanity

python3 --version
git --version

2) Environment reproducibility

cd ~/ai/mint-ai-stack
./bootstrap.sh

Expected result: Installs succeed without manual intervention and prints package versions.

3) PyTorch compute check

source .venv/bin/activate
python verify_torch.py

Expected result: Script prints device and timing; GPU path shows cuda available: True on NVIDIA systems with drivers installed.

4) Jupyter kernel selection

source .venv/bin/activate
jupyter lab

Expected result: You can create a notebook using Python (mint-ai-stack) and import torch, numpy, pandas.

Next Steps: Make it even more robust (and faster)

1) Add containers for “known-good” GPU stacks

Do this if you need strict reproducibility across machines or team members, or you want to avoid host driver/library conflicts. Use Docker/Podman plus NVIDIA Container Toolkit for NVIDIA GPUs.

Why: Containers freeze user-space dependencies. Your host only needs stable GPU drivers.

2) Add pre-commit and formatting

source .venv/bin/activate
uv pip install ruff black pre-commit
pre-commit install

Why: Consistent formatting prevents “it works on my machine” diffs and speeds up collaboration.

3) Add model tooling

• Install Hugging Face stack for NLP/LLMs:

source .venv/bin/activate
uv pip install transformers datasets accelerate safetensors

4) Keep the OS stable; update deliberately

Why: GPU stacks are sensitive to kernel/driver updates. Update in batches, and snapshot before major changes.

Conclusion: Your Mint 22.3 AI workstation, built for repeatability

You now have a lightweight Linux Mint 22.3 Cinnamon workstation configured for local AI development with:

• A reproducible Python environment using venv + uv lockfiles
• A safe workflow for GPU enablement (NVIDIA driver via Driver Manager; ROCm guidance and alternatives for AMD)
• Jupyter configured with a dedicated kernel so imports don’t mysteriously break
• Verification scripts that prove your compute stack works after updates

Keep your system stable, isolate your Python deps, snapshot before driver changes, and you’ll have a development machine that stays fast and dependable for years.