1 05/11/2026 11 min

Su Windows, la strada più pulita per lavorare con Ruby on Rails non è quasi mai l’installazione nativa pura, ma l’uso di WSL2. In pratica, fai girare Linux dentro Windows, con un ambiente molto più vicino a quello reale di sviluppo e deploy. Se provi a forzare Ruby, Bundler, gem native e database direttamente su Windows, i problemi arrivano quasi sempre quando entrano in gioco estensioni compilate, dipendenze di sistema e differenze nel comportamento del filesystem.

Se l’obiettivo è sviluppare seriamente con Rails su Windows, la combinazione più stabile è questa: Windows come sistema host, WSL2 come ambiente Linux, Ruby installato dentro WSL, Rails gestito con un version manager come rbenv o asdf. Il risultato è un setup più prevedibile, più compatibile con la documentazione ufficiale e più facile da trasferire su server Linux o CI.

Perché WSL2 è la scelta giusta

Rails non è difficile da installare in sé; il punto critico è l’ecosistema che gli ruota attorno. Ruby usa gemme native, Bundler risolve dipendenze, alcune gemme richiedono librerie di sistema, e spesso entrano in gioco Node.js, Yarn o database locali. Su Windows nativo questi passaggi possono funzionare, ma il margine di attrito è più alto.

Con WSL2 ottieni invece un Linux vero, con pacchetti coerenti, permessi più simili a quelli di produzione e una toolchain che si comporta come ci si aspetta nei manuali Rails. In più, se in futuro devi spostare il progetto su una VPS o in container, il salto è molto meno traumatico.

Prerequisiti minimi

Prima di iniziare, verifica di avere:

  • Windows 10 o Windows 11 con supporto WSL2 attivo.
  • Virtualizzazione abilitata nel BIOS/UEFI.
  • Almeno 8 GB di RAM, meglio 16 GB se userai anche database e IDE pesanti.
  • Spazio disco sufficiente per distribuzione Linux, gemme e dipendenze JavaScript.

Se WSL2 non è già presente, puoi abilitarlo da PowerShell con privilegi amministrativi. Il comando sotto è quello standard, ma se la tua macchina è gestita da policy aziendali potrebbe essere bloccato: in quel caso va verificata la configurazione con l’amministratore di sistema.

wsl --install

Dopo il riavvio, controlla la presenza della distribuzione Linux e la versione di WSL:

wsl -l -v

L’output atteso mostra la distribuzione installata e la colonna VERSION impostata su 2. Se vedi 1, conviene convertire la distro prima di andare avanti.

Scelta della distribuzione Linux

Per Rails vanno bene Ubuntu, Debian e altre distribuzioni comuni. Se vuoi il percorso più lineare, Ubuntu è spesso la scelta più semplice perché la documentazione e molti esempi online la considerano di fatto il riferimento. Non è un obbligo tecnico, ma riduce il rischio di divergenze nei nomi dei pacchetti.

Una volta installata la distro, aprila dal menu Start e completa la configurazione iniziale dell’utente Linux. È importante ricordare che questo utente non è il tuo account Windows: è l’utente della distribuzione dentro WSL.

Aggiornare il sistema Linux dentro WSL

Prima di installare Ruby, aggiorna l’elenco dei pacchetti e i pacchetti già presenti. Questo evita di lavorare con librerie vecchie o repository non allineati.

sudo apt update
sudo apt upgrade -y

Se l’aggiornamento segnala errori sui mirror o sul DNS, il problema non è Rails: va risolto prima il networking della distro. In WSL, un test rapido è verificare se il sistema riesce a risolvere e raggiungere un host esterno.

ping -c 3 google.com

Se il ping fallisce per risoluzione nome, il problema è lato DNS della distro o dell’host Windows. Se fallisce solo l’ICMP ma apt update funziona, puoi ignorarlo: non è un indicatore affidabile per la connettività applicativa.

Installare le dipendenze di base

Rails richiede un minimo di strumenti di compilazione e librerie di supporto. Le dipendenze esatte possono variare in base alle gemme che userai, ma una base sensata su Ubuntu in WSL è questa:

sudo apt install -y \ build-essential \ git \ curl \ libssl-dev \ libreadline-dev \ zlib1g-dev \ libyaml-dev \ libgmp-dev

Questi pacchetti servono perché molte versioni di Ruby, o gemme con estensioni native, hanno bisogno di compilazione locale. build-essential porta con sé il compilatore e gli strumenti di base; le librerie SSL, readline, zlib e YAML coprono una buona parte dei casi comuni.

Installare Ruby con rbenv

Per gestire più versioni di Ruby senza sporcare il sistema, rbenv è una scelta molto pratica. Evita di installare Ruby con i pacchetti della distribuzione, perché spesso sono più vecchi di quanto serva e possono complicare gli aggiornamenti del progetto.

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv
src/configure
make -C src # Aggiunge rbenv alla shell corrente
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(~/.rbenv/bin/rbenv init - bash)"

Per rendere permanente la configurazione, aggiungi le righe nel file di inizializzazione della shell, ad esempio ~/.bashrc o ~/.zshrc, a seconda della shell usata dentro WSL.

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(~/.rbenv/bin/rbenv init - bash)"' >> ~/.bashrc
source ~/.bashrc

Verifica che il comando sia disponibile:

rbenv -v

L’output atteso è una versione di rbenv, non un errore di comando non trovato. Se il comando non viene riconosciuto, il problema è quasi sempre il PATH o il caricamento della shell.

Installare Ruby

A questo punto puoi installare una versione di Ruby compatibile con Rails. Se non hai requisiti specifici, scegli una versione moderna ma stabile, coerente con la versione di Rails che intendi usare. Il punto non è “l’ultima disponibile” in assoluto, ma una combinazione compatibile con il progetto.

rbenv install 3.3.5
rbenv global 3.3.5
ruby -v

Il comando ruby -v deve restituire la versione appena installata. Se invece vedi la Ruby di sistema o un errore, significa che rbenv non sta intercettando correttamente l’esecuzione. In quel caso, controlla l’ordine del PATH e il caricamento dell’init della shell.

Per evitare sorprese, aggiorna anche RubyGems e Bundler:

gem update --system
gem install bundler

Installare Rails

Con Ruby e Bundler in ordine, l’installazione di Rails è diretta. Anche qui, la versione va scelta in base al progetto: se ne apri uno nuovo, conviene allinearsi a una release supportata e documentata, non a una versione casuale trovata online.

gem install rails
rails -v

Se rails -v risponde con una versione, la base è pronta. Se compare un errore di permessi, non installare tutto con privilegi elevati: vuol dire che l’ambiente utente non è configurato bene. Con rbenv, le gemme dovrebbero vivere nella home dell’utente Linux, non in cartelle di sistema.

Creare il primo progetto Rails

Per testare che tutto funzioni davvero, crea un progetto di prova. È il controllo più utile, perché verifica insieme Ruby, Rails, Bundler e la toolchain di base.

rails new demo_rails

Se vuoi evitare subito il database predefinito o usare un database specifico, puoi passare opzioni diverse. Per esempio, se il progetto finale userà PostgreSQL, è meglio impostarlo da subito invece di migrare dopo.

rails new demo_rails -d postgresql

Entra nella directory del progetto e avvia il server di sviluppo:

cd demo_rails
bin/rails server

Nel browser, apri l’indirizzo mostrato in console, di solito http://127.0.0.1:3000 o http://localhost:3000. La pagina di benvenuto di Rails conferma che il server è attivo e che la catena Ruby/Rails/WSL funziona.

Node.js, JavaScript e asset pipeline

Molti progetti Rails moderni usano anche Node.js per la gestione di asset, build frontend o tool JavaScript. La dipendenza precisa varia in base alla versione di Rails e alla configurazione del progetto, ma in generale serve una runtime JS installata dentro WSL, non su Windows host, per evitare incongruenze tra ambienti.

Se il progetto richiede Node, puoi installarlo con il package manager della distro oppure con un version manager dedicato. Per coerenza con Ruby, spesso è più comodo usare anche per Node un gestore di versioni, così puoi allineare il progetto a una versione specifica senza impattare sugli altri lavori.

Per verificare che la runtime sia disponibile:

node -v
npm -v

Se il progetto usa importmap, la dipendenza su Node può essere minore. Se invece usa bundling più tradizionale o strumenti frontend più strutturati, la presenza di Node diventa fondamentale.

Database locali: SQLite, PostgreSQL, MySQL

Per un test rapido, SQLite è il percorso più semplice perché non richiede un servizio separato. Per un progetto reale, però, PostgreSQL è spesso la scelta più comune in ambiente Rails. MySQL resta valido, ma conviene scegliere il database in base allo stack del progetto e non per abitudine.

Se usi PostgreSQL, installalo nella distro e avvialo come servizio. Il comando esatto dipende dalla versione della distribuzione, ma il flusso è questo: installazione pacchetto, avvio servizio, configurazione utente e database del progetto. Se il servizio non parte, controlla prima i log del demone e lo stato del servizio, non il codice Rails.

sudo apt install -y postgresql postgresql-contrib
sudo service postgresql start
sudo service postgresql status

Se il progetto richiede credenziali specifiche, non metterle in chiaro nel codice o nella documentazione condivisa. Usa variabili d’ambiente, file ignorati da Git o secret manager appropriati. È una regola banale, ma in ambiente di team fa la differenza tra un setup ordinato e una fuga accidentale di credenziali.

Problemi tipici su Windows e come evitarli

Il primo errore classico è mischiare file system Windows e file system Linux senza criterio. Se lavori in WSL, tieni il progetto dentro il filesystem Linux, ad esempio nella home dell’utente, non sotto /mnt/c. In molti casi funziona anche lì, ma le prestazioni e il comportamento di alcune operazioni di file watching peggiorano sensibilmente.

Il secondo errore è installare metà stack su Windows e metà stack su WSL. Ad esempio: Ruby in WSL, ma Node su Windows host. Oppure Git su Windows e bundler dentro Linux, con percorsi misti. Questo tipo di ibridazione crea problemi difficili da leggere, soprattutto quando entrano in gioco path, permessi e watcher.

Il terzo errore è non distinguere il browser di Windows dal server di WSL. Il server gira dentro Linux, ma lo apri dal browser di Windows. Questo è normale. Non bisogna “spostare” il server su Windows per vedere la pagina: basta usare l’indirizzo locale indicato da Rails.

IDE e editor: come lavorare senza attriti

Visual Studio Code con estensione Remote - WSL è una delle combinazioni più comode. In questo modo apri la cartella del progetto direttamente nell’ambiente Linux, ma continui a usare l’interfaccia di Windows. È un buon equilibrio tra ergonomia e coerenza tecnica.

Se usi un altro editor, il criterio resta lo stesso: apri il progetto nel contesto WSL, non come cartella Windows montata a caso. L’ideale è che anche terminale, editor, Ruby e database parlino tutti la stessa lingua di sistema.

Quando ha senso installare Ruby nativamente su Windows

L’installazione nativa può avere senso solo in casi particolari: test rapidi, vincoli aziendali, progetti molto semplici o necessità di lavorare senza WSL per policy. In questi casi bisogna accettare che alcune gemme potrebbero richiedere passaggi in più, e che il comportamento generale non sarà identico a quello di Linux.

Se vuoi comunque tentare la strada nativa, la scelta più nota è usare installer e tool specifici per Windows, ma il consiglio tecnico resta prudente: valuta prima WSL2. È meno elegante dal punto di vista “Windows puro”, ma molto più robusto sul piano operativo.

Verifiche finali prima di iniziare a sviluppare

Prima di considerare il setup concluso, controlla questi punti:

  • WSL2 attivo: wsl -l -v mostra la distro con versione 2.
  • Ruby corretto: ruby -v mostra la versione installata con rbenv.
  • Rails disponibile: rails -v risponde senza errori.
  • Progetto avviabile: bin/rails server porta alla pagina di benvenuto nel browser.
  • Dipendenze allineate: eventuale Node, database e gemme native sono installati nella stessa shell WSL.

Se uno di questi punti fallisce, conviene fermarsi lì e correggere la base, invece di aggiungere ulteriori pacchetti o cambiare versione a caso. Nei setup Rails, la stabilità arriva quasi sempre da un ambiente coerente, non da una lista infinita di workaround.

Flusso consigliato in pratica

Se vuoi una sintesi operativa, il percorso più sensato è questo: abilita WSL2, installa una distro Linux, aggiorna i pacchetti, installa le dipendenze base, configura rbenv, installa Ruby, poi Rails, quindi crea un progetto di test e verifica il server locale. Solo dopo aggiungi Node, database e strumenti accessori in base al progetto reale.

Questa sequenza riduce gli errori di diagnosi. Se qualcosa si rompe, sai esattamente in quale punto della catena è nato il problema: virtualizzazione, shell, Ruby, gemme, Rails o servizi esterni. È il modo più semplice per evitare il classico setup “funziona solo finché non tocchi niente”.

In un ambiente di sviluppo serio, la qualità del setup iniziale pesa più della quantità di tool installati. Con Rails su Windows, questo significa dare priorità alla coerenza del sistema, non alla scorciatoia più veloce.