> ## Documentation Index
> Fetch the complete documentation index at: https://docsmlx.otterly.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation & Setup
> Installer MLX et mlx-lm sur votre Mac pour exécuter des modèles locaux
## 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
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
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` :
```bash theme={null}
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
```bash theme={null}
pip install pandas huggingface_hub "huggingface_hub[cli]"
```
Avec `uv` :
```bash theme={null}
uv pip install pandas huggingface_hub "huggingface_hub[cli]"
```
***
## Vérifier l'installation
Vérifiez d'abord la couche MLX :
```bash theme={null}
python -c "import mlx.core as mx; print(mx.array([1, 2, 3]))"
```
Puis vérifiez la couche LLM :
```bash theme={null}
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 :
```bash theme={null}
source .venv/bin/activate
```
Pour le quitter :
```bash theme={null}
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é
```bash theme={null}
huggingface-cli login
```
Si vous avez installé l'extra CLI, vous pouvez aussi utiliser :
```bash theme={null}
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`.
```swift theme={null}
// 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 :
```bash theme={null}
swift package resolve
swift build
```
Si vous travaillez dans une **app Xcode**, le plus simple est d'utiliser `File > Add Package Dependencies...` avec :
```text theme={null}
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 :
```bash theme={null}
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](/mlx/foundation-models/introduction).
***
## 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` :
```bash theme={null}
pyenv versions
pyenv version
```
Si `3.11.9` est installée mais pas activée, essayez :
```bash theme={null}
pyenv global 3.11.9
pyenv rehash
python --version
```
Si `python` ne marche toujours pas dans le même terminal, initialisez `pyenv` dans `zsh` :
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
python3.11 -m venv .venv
ls .venv/bin/activate
```
Si le fichier existe, l'activation suivante doit fonctionner :
```bash theme={null}
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 :
```bash theme={null}
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 :
```bash theme={null}
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
***
Générer votre premier texte avec `mlx-lm`.