Installer Ruby et Rails : l’environnement de A à Z

Vous décidez d’apprendre Ruby on Rails, vous ouvrez un terminal… et la première heure part en fumée : une version de Ruby qui refuse de compiler, un gem install qui réclame une bibliothèque absente, ou un tutoriel qui vous fait installer le Ruby « système » que vous regretterez au premier projet sérieux. L’installation est l’étape où le plus de débutants abandonnent — pas parce que c’est dur, mais parce que personne ne montre la méthode propre. On règle ça maintenant.

À la fin de ce tutoriel, vous aurez un environnement Ruby moderne, isolé par projet, et votre première application Rails — AtelierFix, le logiciel de suivi des réparations qu’on construit tout au long du parcours — qui répond sur http://localhost:3000.

🎯 Ce que vous allez apprendre

• Installer les dépendances système exigées par Ruby sous Ubuntu/Debian et macOS ;
• Poser un gestionnaire de versions (Mise) pour jongler entre plusieurs Ruby sans conflit ;
• Installer Ruby 3.4 et Rails 8.1, puis vérifier que chaque maillon répond ;
• Générer une application Rails neuve et la lancer en local ;
• Reconnaître et corriger les trois pannes d’installation les plus courantes.

🛠️ Ce que vous allez construire

Le squelette d’AtelierFix : une application Rails 8.1 fraîchement générée, avec sa base SQLite, son serveur de développement et la page d’accueil officielle de Rails. Rien de visible pour un client à ce stade, mais c’est la fondation sur laquelle les tutoriels suivants empilent le modèle de données, les écrans de gestion et l’authentification.

Prérequis

• Un système Linux (Ubuntu/Debian) ou macOS. Sous Windows, installez d’abord WSL 2 et suivez la procédure Ubuntu à l’intérieur — développer Rails en natif sur Windows est une source d’ennuis sans fin.
• Un accès sudo et une connexion correcte : les téléchargements pèsent quelques centaines de Mo.
• Être à l’aise avec un terminal (cd, ls, éditer un fichier). Si ces commandes vous parlent, vous êtes prêt ; sinon, prenez une heure sur les bases du shell avant de continuer.
• ⏱️ Temps estimé : ~30 minutes, hors temps de téléchargement.

Étape 1 — Installer les dépendances système

Ruby n’est pas un binaire isolé : pour le compiler et faire tourner Rails, le système a besoin d’un compilateur C, de la bibliothèque YAML, d’OpenSSL et de quelques outils de build. Les installer avant Ruby évite l’erreur la plus fréquente du débutant — une compilation qui échoue à mi-chemin sur un en-tête manquant. Sous Ubuntu ou Debian (donc aussi sous WSL 2) :

sudo apt update
sudo apt install -y build-essential rustc libssl-dev libyaml-dev zlib1g-dev libgmp-dev git

Cette liste est exactement celle recommandée par le guide officiel d’installation de Rails. build-essential fournit le compilateur C, libyaml-dev est indispensable — Ruby ne fournit plus l’analyseur YAML lui-même, or Rails lit toute sa configuration dans des fichiers .yml — et rustc compile YJIT, le compilateur à la volée (JIT) de Ruby, écrit en Rust, qui accélère sensiblement l’exécution. Sous macOS, le nécessaire vient avec les outils en ligne de commande de Xcode :

xcode-select --install

Une fois la commande terminée sans erreur, le terrain est prêt. On peut passer au gestionnaire de versions.

Étape 2 — Installer Mise, le gestionnaire de versions

Pourquoi ne pas installer Ruby directement avec apt ? Parce que la version des dépôts est souvent ancienne, et surtout parce que vos projets finiront par exiger des versions différentes. Un gestionnaire de versions installe Ruby dans votre dossier utilisateur, vous laisse en garder plusieurs côte à côte, et bascule automatiquement de l’une à l’autre selon le projet. Le guide officiel de Rails recommande désormais Mise (prononcé « mise en place »). Installez-le :

curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
source ~/.bashrc

La première ligne télécharge et installe Mise. La deuxième l’active à chaque ouverture de terminal — remplacez bash par zsh et ~/.bashrc par ~/.zshrc si vous êtes sous macOS, dont le shell par défaut est Zsh. Vérifiez que Mise répond :

mise --version

Vous devriez voir un numéro de version s’afficher (par exemple 2026.x.x). Si la commande est introuvable, fermez puis rouvrez le terminal : la ligne activate n’est lue qu’au démarrage du shell.

Étape 3 — Installer Ruby avec Mise

On installe maintenant Ruby lui-même. Au moment d’écrire, Ruby 4.0 est la dernière version stable, mais la série 3.4 reste la valeur sûre : elle est entièrement supportée par Rails 8.1 et parfaitement rodée. On épingle donc Ruby 3.4 comme version globale par défaut :

mise use -g ruby@3.4

Le drapeau -g (global) en fait votre Ruby par défaut partout. Mise télécharge les sources, les compile (cela peut prendre quelques minutes — c’est normal, ne coupez pas) et l’installe dans votre dossier personnel. Une fois terminé, contrôlez la version active :

ruby --version

La sortie attendue ressemble à ruby 3.4.x. Si vous voyez encore l’ancien Ruby système (souvent 2.7 ou 3.0), c’est que le shell n’a pas rechargé Mise : rouvrez le terminal. Tant que ruby --version n’affiche pas 3.4, inutile d’aller plus loin — tout le reste en dépend.

💡 Plus tard, dans un projet précis, mise use ruby@3.3 (sans -g) écrit un fichier .mise.toml local qui force cette version uniquement dans ce dossier. C’est tout l’intérêt d’un gestionnaire de versions : un projet ancien et un projet neuf cohabitent sans se marcher dessus.

Étape 4 — Installer Rails

Rails se distribue comme une gem (une bibliothèque Ruby). La commande gem install va chercher la dernière version publiée sur RubyGems et l’installe pour le Ruby actif :

gem install rails

L’opération installe Rails et sa cinquantaine de dépendances. Vérifiez ensuite la version :

rails --version

Vous devriez lire Rails 8.1.x. Si la commande rails est introuvable juste après l’installation, lancez mise reshim : Mise doit régénérer les raccourcis vers les exécutables des gems fraîchement posées. Ce petit piège surprend tout le monde une fois.

Étape 5 — Créer AtelierFix et lancer le serveur

Tout est en place : on génère la première application. La commande rails new crée un dossier complet, installe les dépendances et prépare une base de données SQLite — sans rien demander de plus. On nomme le projet atelierfix :

rails new atelierfix
cd atelierfix

En une commande, Rails échafaude une application prête à tourner. Par défaut (Rails 8.1), elle embarque Propshaft pour les assets, Import Maps pour le JavaScript sans build, Hotwire (Turbo + Stimulus) pour l’interactivité, Solid Queue et Solid Cache adossés à la base de données, une configuration Kamal pour le déploiement, et SQLite comme base. C’est un socle de production, pas un jouet. Lancez le serveur de développement :

bin/rails server

Notez le préfixe bin/ : il exécute la version de Rails épinglée pour ce projet, via le binstub local. Le serveur démarre et écoute sur le port 3000. Ouvrez votre navigateur sur http://localhost:3000.

✅ Point d’étape — Vous devez voir la page d’accueil de Rails : son logo et la mention de la version de Rails et de Ruby. Si c’est le cas, votre environnement est complet et AtelierFix existe. Pour arrêter le serveur : Ctrl + C dans le terminal. Si la page ne s’affiche pas, vérifiez qu’aucune autre application n’occupe déjà le port 3000.

Comprendre ce que rails new a créé

Avant de refermer ce tutoriel, prenez deux minutes pour regarder le dossier atelierfix. Rails applique une règle d’or — la convention plutôt que la configuration — et range chaque chose à un endroit précis. Connaître cette carte vous fera gagner un temps fou dès le tutoriel suivant :

• app/ — le cœur de l’application : vos modèles (app/models), contrôleurs (app/controllers) et vues (app/views). C’est là que vous passerez 90 % de votre temps.
• config/ — la configuration. Le fichier config/routes.rb décide quelle URL mène à quel code ; config/database.yml décrit la base.
• db/ — tout ce qui touche à la base de données : les migrations et le schéma. SQLite y dépose son fichier storage/development.sqlite3.
• Gemfile — la liste des bibliothèques (gems) du projet. bundle install les installe d’après ce fichier ; Gemfile.lock verrouille les versions exactes.
• bin/ — les binstubs (bin/rails, bin/kamal…) qui exécutent les bons outils à la bonne version.

Vous n’avez rien à modifier ici tout de suite. Mais quand un tutoriel dira « ouvrez app/models/reparation.rb », vous saurez exactement où aller. Cette discipline de rangement est l’une des raisons pour lesquelles deux développeurs Rails se retrouvent instantanément dans le projet l’un de l’autre.

🐞 Pièges fréquents

🌍 Adaptation au contexte ouest-africain

La compilation de Ruby et le gem install téléchargent beaucoup. Sur une connexion mobile facturée au volume — courant à Dakar, Abidjan ou Bamako — faites-le une fois sur un réseau Wi-Fi correct, puis travaillez hors ligne : une fois Ruby et Rails posés, le développement quotidien ne consomme presque rien. Si une coupure de courant interrompt une compilation, relancez simplement mise install ruby@3.4 : Mise reprend proprement. Et plutôt qu’une machine puissante, un petit portable suffit pour développer ; on ne paiera un serveur (un VPS à quelques milliers de FCFA par mois) qu’au moment du déploiement, couvert dans le dernier tutoriel du parcours.

✅ Récapitulatif

Vous êtes parti d’un terminal vide et vous avez maintenant une chaîne d’outils complète : les dépendances système, Mise pour gérer les versions de Ruby, Ruby 3.4, Rails 8.1, et l’application AtelierFix qui répond sur http://localhost:3000. Surtout, vous avez compris pourquoi on passe par un gestionnaire de versions plutôt que par le Ruby système — une décision qui vous épargnera des heures sur vos prochains projets.

🧾 Aide-mémoire

💪 À vous de jouer

Installez une seconde version de Ruby (par exemple mise use ruby@3.3 dans un nouveau dossier de test) et vérifiez avec ruby --version que la version change selon le dossier où vous vous trouvez. C’est l’expérience qui ancre vraiment la notion de version par projet.

mkdir ~/test-ruby33 && cd ~/test-ruby33
mise use ruby@3.3
ruby --version   # ruby 3.3.x ici
cd ~/atelierfix
ruby --version   # ruby 3.4.x là

Tutoriels frères

• Rails MVC : routes, contrôleurs et vues en pratique — comprendre comment une requête devient une page.
• Active Record : modèles, migrations et associations — donner une base de données à AtelierFix.

Pour aller plus loin

• 🔝 Retour au guide principal : Ruby on Rails : le guide complet pour débuter
• Documentation officielle : Install Ruby on Rails (rubyonrails.org)
• Prochaine étape conseillée : le tutoriel MVC, pour faire afficher votre première page sur mesure.

FAQ

Faut-il installer Ruby 4.0 ou rester sur 3.4 ?
Pour débuter, restez sur Ruby 3.4 : Rails 8.1 la supporte totalement et elle est éprouvée. Ruby 4.0 fonctionne aussi (Rails 8.1 exige au minimum Ruby 3.2), mais inutile de viser le tout dernier numéro tant que vous apprenez.

Mise, rbenv ou RVM : lequel choisir ?
Les trois gèrent les versions de Ruby. Le guide officiel de Rails recommande aujourd’hui Mise, plus rapide et capable de gérer aussi Node, Python, etc. Si vous avez déjà rbenv en place et qu’il fonctionne, gardez-le ; sinon, partez sur Mise.

Puis-je développer sous Windows sans WSL ?
Techniquement oui, via RubyInstaller, mais beaucoup de gems et d’outils (dont le déploiement) supposent un environnement Unix. WSL 2 vous donne un vrai Ubuntu dans Windows : c’est la voie recommandée et sans surprises.

Pourquoi bin/rails et pas rails ?
bin/rails utilise la version de Rails verrouillée pour le projet (via le Gemfile.lock). Sur une machine où coexistent plusieurs projets, c’est la garantie d’exécuter la bonne version à chaque fois.