Baixando Laravel no Windows 11: instalação com WSL 2

Reuni aqui um roteiro para começar com Laravel no Windows 11 usando um ambiente Linux. A ideia é chegar a um projeto aberto no navegador e entender onde cada comando deve ser executado.

Nesta anotação, escolhi Laravel 13, PHP 8.5, Node 24 LTS e SQLite. O Windows continua sendo o sistema principal; Ubuntu, PHP e as ferramentas do projeto ficam dentro do WSL 2. Você não precisa instalar Docker ou um servidor MySQL para acompanhar.

Os comandos foram conferidos na documentação oficial indicada ao longo do texto. Este roteiro não representa um teste completo executado em uma instalação de Windows 11.

Antes de começar

Tenha Windows 11 atualizado, acesso de administrador para habilitar o WSL, conexão com a internet e espaço disponível para Ubuntu e as dependências. A virtualização precisa estar habilitada no computador. Se a instalação apontar esse problema, consulte o fabricante para habilitá-la no firmware.

Vou identificar os blocos com PowerShell · Windows ou Ubuntu · Bash. Copie apenas os comandos do bloco correspondente e espere cada etapa terminar antes de continuar. O terminal do Ubuntu também pode aparecer como uma aba no Windows Terminal.

O WSL permite executar ferramentas Linux junto dos aplicativos Windows. O procedimento inicial segue a instalação oficial do WSL.

Instalar e atualizar o WSL 2

Abra o menu Iniciar, procure PowerShell e escolha Executar como administrador. Instale o WSL com Ubuntu:

PowerShell · Windows (administrador)

wsl --install -d Ubuntu

Reinicie o Windows quando solicitado. Depois, abra novamente o PowerShell para atualizar e conferir a instalação:

PowerShell · Windows

wsl --update
wsl --status
wsl --list --verbose

Na lista, procure Ubuntu e confira se a coluna VERSION mostra 2. Essa coluna indica a geração do WSL, não a versão do Ubuntu. Se a distribuição já existia em WSL 1, faça a conversão:

PowerShell · Windows

wsl --set-version Ubuntu 2

Use o nome exato mostrado pela listagem caso ele seja diferente. A referência de comandos do WSL explica essas opções e a diferença entre versão padrão e versão de uma distribuição existente.

Abrir o Ubuntu e criar seu usuário

Abra Ubuntu pelo menu Iniciar. Na primeira inicialização, aguarde a preparação e crie um nome de usuário Linux e uma senha. Eles pertencem ao Ubuntu e podem ser diferentes do login do Windows. Ao digitar a senha, nenhum caractere aparece: isso é normal.

A partir daqui, os comandos de instalação das ferramentas são executados no Ubuntu. Atualize os pacotes e instale os utilitários básicos:

Ubuntu · Bash

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ca-certificates git unzip

sudo pede a senha Linux e executa essa operação com privilégios administrativos. Depois, prepare uma pasta de projetos dentro do seu diretório pessoal:

Ubuntu · Bash

mkdir -p ~/projetos
cd ~/projetos
pwd

O caminho deve começar com /home/ e incluir seu usuário. Mantenha este projeto ali: a Microsoft recomenda guardar arquivos no sistema de arquivos das ferramentas que os utilizam. Para ferramentas Linux, isso evita o custo de trabalhar atravessando a pasta Windows em /mnt/c. Veja a preparação do ambiente WSL.

Instalar PHP 8.5 e Composer

Laravel 13 exige PHP 8.3 ou superior; aqui adoto PHP 8.5, conforme a matriz de suporte do Laravel 13. PHP executa a aplicação, enquanto Composer resolve suas dependências.

A documentação Laravel fornece um instalador Linux para PHP, Composer e a ferramenta laravel. Execute a variante Linux dentro do Ubuntu:

Ubuntu · Bash

/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.5)"

Esse comando baixa e executa o instalador indicado na documentação de instalação do Laravel. Confira a origem antes de executá-lo. Quando terminar, feche e abra novamente o terminal Ubuntu para carregar o caminho das ferramentas.

Verifique as versões:

Ubuntu · Bash

php -v
composer --version
laravel --version

Espere PHP 8.5.x. A versão exibida por laravel --version é a do instalador, não a do framework do projeto. Vamos conferir o framework depois de criar a aplicação.

Instalar Node 24 com NVM

Node e npm cuidam das ferramentas de frontend. Vou fixar a linha 24 LTS, indicada na tabela de versões do Node.js, em vez de deixar o tutorial depender da versão mais nova disponível.

Instale o NVM no Ubuntu com o comando publicado pelo projeto oficial nvm-sh:

Ubuntu · Bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash

O script configura o carregamento do NVM no shell. No Bash padrão do Ubuntu, recarregue essa configuração e instale Node:

Ubuntu · Bash

source ~/.bashrc
command -v nvm
nvm install 24
nvm alias default 24
nvm use 24
node --version
npm --version

O primeiro comando de verificação deve encontrar nvm; Node deve mostrar v24.x.x. npm acompanha essa instalação. Não use sudo para instalar pacotes npm dentro do projeto.

Criar o projeto Laravel 13

Para manter esta anotação reproduzível mesmo depois de um novo lançamento principal, vou criar a aplicação pelo Composer com a restrição ^13.0. A opção create-project é documentada no manual do Composer.

Ubuntu · Bash

cd ~/projetos
composer create-project laravel/laravel meu-primeiro-laravel "^13.0"
cd meu-primeiro-laravel
php artisan --version
composer check-platform-reqs

Use uma pasta nova: se meu-primeiro-laravel já existir e tiver arquivos, escolha outro nome. A instalação baixa o esqueleto e suas dependências. php artisan --version deve mostrar Laravel Framework 13.x; a última linha verifica PHP e extensões exigidas pelas dependências instaladas.

O arquivo composer.json descreve as dependências PHP e artisan é a interface de comandos da aplicação. Você encontrará as rotas em routes/web.php e a página inicial em resources/views/welcome.blade.php. Esses são bons primeiros arquivos para explorar depois que o ambiente estiver funcionando.

Usar SQLite no primeiro projeto

SQLite guarda o banco em um arquivo local e dispensa um servidor separado. O projeto Laravel novo usa essa opção por padrão. No editor, confira se o arquivo .env contém esta configuração:

Arquivo .env · configuração, não executar no terminal

DB_CONNECTION=sqlite

O arquivo esperado é database/database.sqlite. Você pode conferir as migrações e a extensão usada pelo PHP:

Ubuntu · Bash

php --ri pdo_sqlite
php artisan migrate:status

Se o banco ainda não tiver sido criado, prepare o arquivo e rode as migrações neste projeto novo:

Ubuntu · Bash

touch database/database.sqlite
php artisan migrate

As migrações criam as tabelas definidas pela aplicação. Não use comandos que apagam tabelas para resolver um erro de instalação. Se alterou .env depois de testar outra configuração, execute php artisan config:clear antes de tentar novamente.

O .env pode conter credenciais: mantenha-o fora do controle de versão e não publique seu conteúdo. A documentação de banco do Laravel detalha o SQLite; a documentação de configuração explica o ambiente e seu cache.

Executar e abrir no navegador

Dentro de ~/projetos/meu-primeiro-laravel, instale e compile os arquivos de frontend:

Ubuntu · Bash

npm install
npm run build

Agora inicie o ambiente de desenvolvimento:

Ubuntu · Bash

composer run dev

Mantenha esse terminal aberto. O script inicia os processos de desenvolvimento da aplicação. Abra http://localhost:8000 no navegador do Windows. Se o terminal informar outra porta, use o endereço efetivamente mostrado.

A página padrão do Laravel deve aparecer. O servidor do Vite atende os recursos de frontend durante o desenvolvimento; a porta dele não substitui o endereço da aplicação. A documentação do Vite no Laravel explica desenvolvimento e compilação. O acesso do Windows a serviços do WSL por localhost está descrito na documentação de rede do WSL.

Editar com VS Code e WSL

Instale o VS Code no Windows e a extensão WSL, da Microsoft. Na instalação do editor, mantenha habilitada a opção de adicionar o comando code ao PATH.

Em outra aba do Ubuntu, abra a pasta:

Ubuntu · Bash

cd ~/projetos/meu-primeiro-laravel
code .

Na primeira abertura, o editor prepara seu servidor no WSL. Confira o indicador WSL: Ubuntu na janela antes de trabalhar. Um novo terminal integrado nessa janela executará os comandos no Linux.

Se code não for encontrado, reabra o terminal após instalar o editor e confira a opção de PATH. Também é possível abrir a paleta de comandos do VS Code e usar WSL: Connect to WSL, depois abrir a pasta do projeto. Esses caminhos seguem a documentação do VS Code com WSL.

Encerrar e retomar o ambiente

Para parar a aplicação, volte ao terminal que executa composer run dev e pressione Ctrl+C. Para sair do shell Ubuntu, digite exit.

Quando quiser encerrar o WSL inteiro, salve os arquivos e pare as aplicações antes de executar:

PowerShell · Windows

wsl --shutdown

Esse comando encerra todas as distribuições em execução e pode interromper outras ferramentas que dependem do WSL. Para retomar, abra Ubuntu pelo menu Iniciar ou use:

PowerShell · Windows

wsl -d Ubuntu

Depois, no Ubuntu:

Ubuntu · Bash

cd ~/projetos/meu-primeiro-laravel
nvm use 24
composer run dev

Você não precisa reinstalar o projeto a cada sessão. Se as dependências não mudaram, basta iniciar os processos novamente.

Problemas frequentes

WSL não instala ou fica em 0%

Verifique atualizações do Windows, conexão e virtualização. Se o download pela loja ficar preso, a Microsoft documenta a alternativa wsl --install --web-download -d Ubuntu. Use-a no PowerShell como administrador. Para erros específicos, consulte a solução de problemas do WSL, sem desinstalar a distribuição ou apagar seus arquivos como primeiro recurso.

PHP, Composer ou NVM não são encontrados

Confirme que você está no Ubuntu, reabra o terminal e tente novamente. Para NVM no Bash, source ~/.bashrc recarrega sua configuração. Para verificar qual executável está sendo usado, execute command -v php e command -v composer. Um caminho sob /mnt/c indica uma ferramenta Windows; revise a instalação Linux antes de continuar.

“Could not open input file: artisan”

O comando foi executado fora da raiz da aplicação. Entre em ~/projetos/meu-primeiro-laravel e confira se o arquivo artisan está presente antes de repetir.

“Could not find driver” ao acessar o banco

Confira php --ri pdo_sqlite e composer check-platform-reqs. Se a extensão não aparecer, revise qual PHP está no PATH e a instalação indicada acima. Não instale pacotes de outra versão de PHP às cegas: a extensão precisa pertencer ao executável usado pelo projeto.

A página não abre ou a porta já está ocupada

Confira se composer run dev continua ativo e leia seu erro no terminal. Para isolar uma disputa pela porta 8000, pare o script com Ctrl+C e execute php artisan serve --port=8001; em uma segunda aba Ubuntu, dentro do projeto, execute npm run dev. Acesse http://localhost:8001. Ao terminar, pare os dois terminais com Ctrl+C.

“Vite manifest not found”

Na raiz do projeto, execute npm install e npm run build. Para continuar desenvolvendo com atualização automática, use composer run dev. Confira os erros do npm antes de recarregar a página.

Próximo passo e referências

Com a aplicação aberta, uma primeira experiência simples é alterar o texto de resources/views/welcome.blade.php e observar a mudança no navegador. Depois, explore rotas do Laravel e templates Blade.

Deixo reunidas as referências principais para consultar quando alguma versão ou tela mudar:

• Instalar WSL - Microsoft.
• Comandos do WSL - Microsoft.
• Ambiente de desenvolvimento WSL - Microsoft.
• Instalação do Laravel 13.
• Linha de comando do Composer.
• Instalação do NVM - nvm-sh.
• Ciclo de versões do Node.js.
• VS Code com WSL - Microsoft.