Installation & Setup

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

`pyenv: python: command not found`

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

`source .venv/bin/activate`: no such file or directory

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

`pip` ou `python` ne sont trouvés qu'après activation

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.

`mlx_lm.generate` n'existe pas

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

Le chargement d'un modèle échoue par manque de mémoire

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.

Je développe en Swift et je ne sais pas quoi installer

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.

Démarrer

Modèles

Ressources

Avant de commencer

Vérifier l’architecture de Python

Installer Python

Option 1 : installation classique

Option 2 : installation via `uv`

Installer MLX et `mlx-lm`

Méthode classique avec `venv`

Méthode avec `uv`

Pourquoi ajouter `pandas` et `huggingface_hub`

Vérifier l’installation

Activer et quitter l’environnement

Avec la méthode classique

Avec `uv`

Connexion à Hugging Face

Installer les outils Swift

Problèmes fréquents

Étape suivante : prise en main rapide

​Avant de commencer

​Vérifier l’architecture de Python

​Installer Python

​Option 1 : installation classique

​Option 2 : installation via uv

​Installer MLX et mlx-lm

​Méthode classique avec venv

​Méthode avec uv

​Pourquoi ajouter pandas et huggingface_hub

​Vérifier l’installation

​Activer et quitter l’environnement

​Avec la méthode classique

​Avec uv

​Connexion à Hugging Face

​Installer les outils Swift

​Problèmes fréquents

Étape suivante : prise en main rapide

Avant de commencer

Vérifier l’architecture de Python

Installer Python

Option 1 : installation classique

Option 2 : installation via `uv`

Installer MLX et `mlx-lm`

Méthode classique avec `venv`

Méthode avec `uv`

Pourquoi ajouter `pandas` et `huggingface_hub`

Vérifier l’installation

Activer et quitter l’environnement

Avec la méthode classique

Avec `uv`

Connexion à Hugging Face

Installer les outils Swift

Problèmes fréquents