---

name: setup-wsl-dev-environment description: > Configura un entorno de desarrollo WSL2 en Windows, incluyendo configuración de shell, herramientas esenciales, Git, claves SSH, Node.js, Python y gestión de rutas multiplataforma. Usar al configurar una nueva máquina Windows para desarrollo, al configurar WSL2 por primera vez, al añadir herramientas de desarrollo a una instalación WSL existente, o al establecer flujos de trabajo multiplataforma que combinen WSL y herramientas de Windows. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: general complexity: intermediate language: multi tags: wsl, windows, linux, development, setup locale: es source_locale: en source_commit: 6f65f316 fence_basis_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16

Configurar el Entorno de Desarrollo WSL

Configura un entorno de desarrollo WSL2 completo para trabajo multiplataforma.

Cuándo Usar

• Al configurar una nueva máquina Windows para desarrollo
• Al configurar WSL2 por primera vez
• Al añadir herramientas de desarrollo a una instalación WSL existente
• Al establecer flujos de trabajo multiplataforma (WSL + herramientas de Windows)

Entradas

• Requerido: Windows 10/11 con soporte para WSL2
• Opcional: Distribución de Linux preferida (por defecto: Ubuntu)
• Opcional: Lenguajes a configurar (Node.js, Python, R)
• Opcional: Herramientas adicionales (Docker, tmux, fzf)

Procedimiento

Paso 1: Instalar WSL2

En PowerShell (Administrador):

wsl --install
wsl --set-default-version 2

Reiniciar si se solicita. Ubuntu se instala por defecto.

Esperado: Tras el reinicio, wsl --list --verbose muestra la distribución ejecutándose bajo la versión 2 de WSL. El comando wsl abre una shell de Linux.

En caso de fallo: Si la instalación de WSL2 falla, habilita manualmente las características de Windows "Virtual Machine Platform" y "Windows Subsystem for Linux" mediante optionalfeatures.exe. En versiones antiguas de Windows 10, puede ser necesaria una actualización del kernel de Microsoft.

Paso 2: Configurar los Límites de Recursos de WSL

Crear ~/.wslconfig en el directorio home de Windows:

[wsl2]
memory=8GB
processors=4
localhostForwarding=true

Esperado: El archivo .wslconfig existe en el directorio home del usuario de Windows (p.ej., C:\Users\Nombre\.wslconfig). Tras ejecutar wsl --shutdown y reiniciar WSL, los límites de recursos se aplican.

En caso de fallo: Si la configuración no tiene efecto, verifica que el archivo está en la ubicación correcta (home de Windows, no home de WSL). Ejecuta wsl --shutdown y vuelve a abrir WSL para que los cambios surtan efecto.

Paso 3: Actualizar e Instalar Esenciales

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  build-essential \
  curl \
  wget \
  git \
  git-lfs \
  vim \
  htop \
  tree \
  jq \
  ripgrep \
  fd-find \
  unzip \
  zip

Crear alias útiles:

echo 'alias fd="fdfind"' >> ~/.bashrc

Esperado: Todos los paquetes se instalan sin errores. Comandos como git --version, jq --version, rg --version y tree se ejecutan correctamente.

En caso de fallo: Si apt install falla, ejecuta primero sudo apt update para actualizar las listas de paquetes. Para paquetes no encontrados, verifica que la versión de Ubuntu los soporte o instálalos desde fuentes alternativas (p.ej., snap, cargo, o descarga manual).

Paso 4: Configurar Git

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global init.defaultBranch main
git config --global core.autocrlf input
git config --global color.ui auto
git config --global core.editor vim

Esperado: git config --list muestra el nombre de usuario, correo, rama por defecto (main), autocrlf (input) y configuración del editor correctos.

En caso de fallo: Si los ajustes no se aplican, verifica que usaste --global (no --local, que solo aplica al repositorio actual). Comprueba que ~/.gitconfig contiene las entradas esperadas.

Paso 5: Configurar Claves SSH

ssh-keygen -t ed25519 -C "your.email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub
# Add to GitHub: Settings > SSH and GPG keys

Prueba: ssh -T git@github.com

Esperado: ssh -T git@github.com devuelve "Hi username! You've successfully authenticated." El par de claves SSH existe en ~/.ssh/id_ed25519 y ~/.ssh/id_ed25519.pub.

En caso de fallo: Si la autenticación falla, verifica que la clave pública fue añadida a GitHub (Settings > SSH and GPG keys). Comprueba que ssh-agent está en ejecución y la clave está cargada con ssh-add -l. Si el agente no está en ejecución, añade eval "$(ssh-agent -s)" a ~/.bashrc.

Paso 6: Instalar Node.js (vía nvm)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

Esperado: node --version y npm --version devuelven las versiones LTS actuales. nvm ls muestra la versión instalada marcada como predeterminada.

En caso de fallo: Si nvm no se encuentra tras la instalación, ejecuta source ~/.bashrc o abre una nueva terminal. Si el script de instalación falla, descárgalo y ejecútalo manualmente tras revisar su contenido.

Paso 7: Instalar Python (vía pyenv)

# Install build dependencies
sudo apt install -y make libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev libncursesw5-dev xz-utils \
  tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

curl https://pyenv.run | bash

# Add to ~/.bashrc
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

pyenv install 3.12
pyenv global 3.12

Esperado: python --version devuelve Python 3.12.x. pyenv versions muestra la versión instalada configurada como global.

En caso de fallo: Si pyenv install falla con errores de compilación, asegúrate de que todas las dependencias del comando apt install fueron instaladas. Las librerías faltantes (especialmente libssl-dev o zlib1g-dev) son la causa más común de errores en la compilación de Python.

Paso 8: Configurar el Shell

Añadir a ~/.bashrc:

# History
export HISTSIZE=10000
export HISTFILESIZE=20000
export HISTCONTROL=ignoredups:erasedups
shopt -s histappend

# Navigation aliases
alias ll='ls -alF'
alias la='ls -A'
alias ..='cd ..'
alias ...='cd ../..'

# Development paths
export DEV_HOME="/mnt/d/dev/p"
alias dev='cd $DEV_HOME'

# Functions
mkcd() { mkdir -p "$1" && cd "$1"; }

# PATH additions
export PATH="$HOME/bin:$HOME/.local/bin:$PATH"

Esperado: Tras ejecutar source ~/.bashrc, todos los alias (ll, la, .., dev) funcionan, la función mkcd crea y entra en directorios, y $DEV_HOME apunta al directorio de desarrollo.

En caso de fallo: Si los alias no están disponibles, verifica que las adiciones fueron añadidas a ~/.bashrc (no a ~/.bash_profile o ~/.profile). Ejecuta source ~/.bashrc para recargar sin abrir una nueva terminal.

Paso 9: Configurar Claude Code CLI

# Add Claude CLI to PATH (after installation)
echo 'export PATH="$HOME/.claude/local/node_modules/.bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
which claude

Esperado: which claude devuelve la ruta al binario de Claude Code CLI (p.ej., ~/.claude/local/node_modules/.bin/claude). Ejecutar claude --version imprime la versión instalada.

En caso de fallo: Si claude no se encuentra, verifica que la exportación del PATH fue añadida a ~/.bashrc y recargada. Comprueba que Claude Code está realmente instalado en ~/.claude/local/. Si no está instalado, sigue primero las instrucciones de instalación de Claude Code.

Paso 10: Referencia de Rutas Multiplataforma

Windows	WSL
C:\Users\Name	/mnt/c/Users/Name
D:\dev\projects	/mnt/d/dev/projects
%APPDATA%	/mnt/c/Users/Name/AppData/Roaming

Abrir el Explorador de Windows desde WSL: explorer.exe .

Esperado: La tabla de conversión de rutas se entiende y se prueba: el acceso a rutas de Windows desde WSL funciona (p.ej., ls /mnt/c/Users/), y explorer.exe . abre el Explorador de Windows en el directorio WSL actual.

En caso de fallo: Si /mnt/c/ no es accesible, verifica que el automontaje de WSL está configurado. Comprueba /etc/wsl.conf para los ajustes [automount]. Ejecuta wsl --shutdown y reinicia si los puntos de montaje están obsoletos.

Validación

• WSL2 ejecutándose con la distribución correcta
• Git configurado con la identidad correcta
• Clave SSH añadida a GitHub y conexión verificada
• Node.js instalado y funcionando
• Python instalado y funcionando
• Alias y funciones del shell funcionan
• Claude Code CLI accesible

Errores Comunes

• Acceso lento a archivos en /mnt/: Almacena los proyectos de acceso frecuente en el sistema de archivos de WSL (~/) para mejor rendimiento. Usa /mnt/ para proyectos compartidos con herramientas de Windows.
• Finales de línea: core.autocrlf=input previene problemas con CRLF. Configura los editores para usar LF.
• Problemas de permisos: Los archivos en /mnt/ pueden mostrar permisos incorrectos. Añadir a /etc/wsl.conf: [automount]\noptions = "metadata,umask=22,fmask=11"
• Windows Defender: Excluye los directorios de WSL del análisis en tiempo real para mejor rendimiento.

Habilidades Relacionadas

• configure-git-repository - configuración detallada de repositorios Git
• configure-mcp-server - la configuración de MCP requiere el entorno WSL
• write-claude-md - configurar el asistente de IA para proyectos