Skip to main content

​
Avant de commencer

Dans ce guide, vous installez MLX et mlx-lm ensemble :
  • mlx fournit les briques de calcul optimisées pour Apple Silicon
  • mlx-lm ajoute les outils LLM utiles au quotidien : chargement de modèles, génération, conversion, quantification, fine-tuning et serveur local
Si votre objectif est de lancer des modèles locaux, installez les deux dès le départ. Ce guide cible le cas le plus simple et le plus courant :
  • un Mac avec Apple Silicon
  • un Python natif arm64
  • un environnement virtuel dédié au projet
Si votre terminal ou votre Python tourne sous Rosetta, vous risquez des erreurs de dépendances ou des performances incohérentes.

​
Vérifier l’architecture de Python

python3 -c "import platform; print(platform.machine())"
Sur Apple Silicon, vous voulez voir arm64.

​
Installer Python

Vous avez deux approches raisonnables :
  • la voie classique : vous installez Python vous-même, puis vous créez un venv
  • la voie uv : uv peut installer Python, créer l’environnement et piloter les commandes

​
Option 1 : installation classique

La voie classique convient si vous utilisez déjà :
  • l’installateur officiel Python
  • Homebrew
  • pyenv
Si python n’existe pas dans votre shell, testez d’abord : 
python3 --version
python3.11 --version
Si python3.11 fonctionne mais pas python, vous pouvez quand même avancer avec python3.11.

​
Option 2 : installation via uv

Si vous partez de zéro, uv simplifie souvent le setup : 
brew install uv
uv python install 3.11
Vous obtenez ainsi une version de Python exploitable sans passer par pyenv.
Si vous débutez ou si votre shell mélange plusieurs installations Python, uv est souvent la voie la plus simple à documenter et à reproduire.

​
Installer MLX et mlx-lm

​
Méthode classique avec venv

Créez un environnement propre, activez-le, puis installez les deux paquets : 
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install mlx mlx-lm
Si la commande python existe déjà correctement sur votre machine, vous pouvez aussi utiliser : 
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install mlx mlx-lm

​
Méthode avec uv

uv peut gérer Python, l’environnement virtuel et l’installation des paquets : 
uv python install 3.11
uv venv --python 3.11 .venv
source .venv/bin/activate
uv pip install mlx mlx-lm
Si vous préférez ne pas activer l’environnement, vous pouvez aussi travailler sans source : 
uv python install 3.11
uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python mlx mlx-lm
uv run --python .venv/bin/python mlx_lm.generate \
  --model mlx-community/Llama-3.2-3B-Instruct-4bit \
  --prompt "Explique MLX en deux phrases simples."

​
Pourquoi ajouter pandas et huggingface_hub

Pour une simple génération locale, mlx et mlx-lm suffisent. Ajoutez ces paquets si vous allez plus loin :
  • pandas est pratique pour préparer, filtrer ou convertir des datasets en csv, jsonl ou tableaux avant un fine-tuning
  • huggingface_hub permet de télécharger, publier et manipuler des dépôts Hugging Face en Python
  • "huggingface_hub[cli]" ajoute les commandes CLI comme hf ou huggingface-cli, utiles pour se connecter, télécharger ou pousser un modèle depuis le terminal
pip install pandas huggingface_hub "huggingface_hub[cli]"
Avec uv : 
uv pip install pandas huggingface_hub "huggingface_hub[cli]"

​
Vérifier l’installation

Vérifiez d’abord la couche MLX : 
python -c "import mlx.core as mx; print(mx.array([1, 2, 3]))"
Puis vérifiez la couche LLM : 
mlx_lm.generate \
  --model mlx-community/Llama-3.2-3B-Instruct-4bit \
  --prompt "Explique la différence entre MLX et Foundation Models."
Au premier lancement, mlx-lm télécharge le modèle depuis Hugging Face puis le réutilise depuis le cache local.
Commencez avec un modèle compact en 4bit. Le téléchargement est plus léger et vous réduisez le risque d’erreur mémoire.

​
Activer et quitter l’environnement

​
Avec la méthode classique

Pour entrer dans l’environnement : 
source .venv/bin/activate
Pour le quitter : 
deactivate

​
Avec uv

Deux usages sont possibles :
  • si vous avez activé .venv avec source .venv/bin/activate, vous le quittez aussi avec deactivate
  • si vous utilisez uv run sans activation, vous n’avez rien à quitter

​
Connexion à Hugging Face

Vous pouvez travailler sans compte pour beaucoup de modèles publics. Connectez-vous seulement si vous voulez :
  • accéder à un dépôt privé
  • publier un modèle converti
  • partager un modèle fine-tuné
huggingface-cli login
Si vous avez installé l’extra CLI, vous pouvez aussi utiliser : 
hf auth login

​
Installer les outils Swift

Cette partie ne concerne que le cas où vous voulez charger un modèle MLX dans une app Swift. Si vous travaillez dans un Swift package, modifiez le fichier Package.swift. 
// Package.swift
import PackageDescription

let package = Package(
    name: "MyApp",
    dependencies: [
        .package(
            url: "https://github.com/ml-explore/mlx-swift",
            branch: "main"
        )
    ],
    targets: [
        .executableTarget(
            name: "MyApp",
            dependencies: [
                .product(name: "MLX", package: "mlx-swift"),
                .product(name: "MLXLLM", package: "mlx-swift"),
                .product(name: "MLXLMCommon", package: "mlx-swift")
            ]
        )
    ]
)
Puis résolvez et compilez : 
swift package resolve
swift build
Si vous travaillez dans une app Xcode, le plus simple est d’utiliser File > Add Package Dependencies... avec : 
https://github.com/ml-explore/mlx-swift
Xcode mettra à jour la configuration du projet pour vous. Vous pouvez ensuite vérifier la résolution des dépendances en CLI : 
xcodebuild -resolvePackageDependencies -scheme MyApp
Si vous voulez utiliser le modèle système Apple dans une app Swift, vous n’avez pas besoin d’installer MLX, mlx-lm ou mlx-swift. Dans ce cas, vous utilisez le framework FoundationModels fourni par Apple et vous travaillez directement avec LanguageModelSession, SystemLanguageModel et les APIs système. Commencez plutôt par Foundation Models.

​
Problèmes fréquents

Ce cas arrive quand pyenv connaît une version Python, mais qu’aucune version exploitable n’est activée pour la commande python dans votre shell actuel.Vérifiez d’abord l’état de pyenv :
pyenv versions
pyenv version
Si 3.11.9 est installée mais pas activée, essayez :
pyenv global 3.11.9
pyenv rehash
python --version
Si python ne marche toujours pas dans le même terminal, initialisez pyenv dans zsh :
eval "$(pyenv init - zsh)"
pyenv global 3.11.9
pyenv rehash
python --version
Pour rendre cela persistant, ajoutez pyenv à votre fichier ~/.zshrc puis rechargez votre shell :
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"
Si vous voulez avancer tout de suite, contournez le problème avec :
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install mlx mlx-lm
Dans votre cas, cette erreur est une conséquence directe de l’étape précédente : l’environnement n’a jamais été créé, car python -m venv .venv a échoué.Vérifiez d’abord que la création du venv fonctionne :
python3.11 -m venv .venv
ls .venv/bin/activate
Si le fichier existe, l’activation suivante doit fonctionner :
source .venv/bin/activate
C’est normal si vous avez créé l’environnement avec python3.11 mais que la commande globale python n’existe pas hors du venv.Une fois .venv activé, python et pip pointent en général vers l’environnement virtuel :
source .venv/bin/activate
which python
which pip
python --version
pip --version
Si ces commandes répondent dans le venv, vous pouvez continuer normalement.
Le paquet mlx seul ne suffit pas. La commande mlx_lm.generate vient de mlx-lm.Réinstallez explicitement les deux paquets dans l’environnement actif :
source .venv/bin/activate
pip install -U mlx mlx-lm
which mlx_lm.generate
Commencez avec un modèle plus petit ou déjà quantifié en 4bit. Fermez aussi les applications qui consomment beaucoup de mémoire unifiée.
Choisissez selon votre objectif :
  • pour une app Swift qui exploite le modèle système Apple, utilisez FoundationModels et n’installez pas MLX
  • pour embarquer un modèle open weight précis dans l’app, ajoutez mlx-swift
  • pour garder l’app légère, servez le modèle à part avec mlx_lm.server puis appelez-le en HTTP

Étape suivante : prise en main rapide

Générer votre premier texte avec mlx-lm.