---
# System prepended metadata

title: '[Windows] WSL'
tags: [linux, OS, command, docker-compose, Ubuntu, docker]

---

[Windows] WSL
===
> Windows Subsystem for Linux

###### tags: `OS`
###### tags: `OS`, `Ubuntu`, `linux`, `command`, `docker`, `docker-compose`

<br>

[TOC]

<br>

## 安裝方式
```cmd=
REM 打開 Windows PowerShell (系統管理員)

> wsl -h


REM 列出線上 Ubuntu 版本
> wsl --list --online
以下是可安裝之有效發佈的清單。
使用 'wsl --install -d <Distro>' 安裝。
NAME            FRIENDLY NAME
Ubuntu          Ubuntu
Debian          Debian GNU/Linux
kali-linux      Kali Linux Rolling
openSUSE-42     openSUSE Leap 42
SLES-12         SUSE Linux Enterprise Server v12
Ubuntu-16.04    Ubuntu 16.04 LTS
Ubuntu-18.04    Ubuntu 18.04 LTS
Ubuntu-20.04    Ubuntu 20.04 LTS


REM 列出本地端 Ubuntu 版本
> wsl --list


> wsl --install -d Ubuntu-20.04

REM [1] 重開機
REM [2] 打開 Windows PowerShell，輸入 wsl
```
### 安裝結果
![](https://i.imgur.com/U8fbE1a.png)
![](https://i.imgur.com/zb9xdch.png)

### 參考資料
- [[官方文件][zh] 安裝 WSL](https://docs.microsoft.com/zh-tw/windows/wsl/install)
- [[官方文件][zh] Install WSL](https://docs.microsoft.com/en-us/windows/wsl/install)
- [介紹好用工具：WSL (Windows Subsystem for Linux)](https://blog.miniasp.com/post/2019/02/01/Useful-tool-WSL-Windows-Subsystem-for-Linux)


<br>

## 操作

### 確認 Ubuntu 版本
```
wsl -d Ubuntu -- cat /etc/os-release
wsl -d Ubuntu -- lsb_release -a
```

### 啟動
輸入 `wsl` 或是 `ubuntu2004`
![](https://i.imgur.com/BJciuP9.png)

![](https://i.imgur.com/E3Ff0Qc.png)

<br>

### Linux OS 在 Windows 中的檔案位置
- 列出磁碟機
    ```
    $ ls /mnt
    c  d  e  g  wsl
    ```
- [跨 Windows 和 Linux 檔案系統運作](https://docs.microsoft.com/zh-tw/windows/wsl/filesystems)
    ```
    \\wsl$
    ```

<br>

## 安裝 Docker Desktop 
> - 企業需要付費
> - [Windows Docker 安装](https://www.runoob.com/docker/windows-docker-install.html)
>   Docker Desktop 是 Docker 在 Windows 10 和 macOS 操作系统上的官方安装方式，这个方法依然属于先在虚拟机中安装 Linux 然后再安装 Docker 的方法。

### 未安裝前，使用 docker 的錯誤訊息
> Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

> Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/json?all=1": dial unix /var/run/docker.sock: connect: permission denied

<br>

### 下載 Docker Desktop 並安裝
1. https://www.google.com/search?q=Docker+Deskto
    ![](https://i.imgur.com/YiNkSXR.png)
2. 下載 windows 版：[Docker Desktop Installer.exe](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=module)
    > 482MB
3. 點擊執行
    ![](https://i.imgur.com/7pXEmJ1.png)
    ![](https://i.imgur.com/mPagrDH.png)
    ![](https://i.imgur.com/n755Bf6.png)
    
底下是哪邊來的圖片？
![](https://i.imgur.com/u5mb67n.png)


### 參考資料
- Google
    - `docker wsl` -> [Docker Desktop WSL 2 backend](https://docs.docker.com/desktop/windows/wsl/)
    - `docker desktop for windows` -> [Docker Desktop for Windows](https://hub.docker.com/editions/community/docker-ce-desktop-windows)

- [Docker not running on Ubuntu WSL due to error cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? [closed]](https://stackoverflow.com/questions/61592709/)
    - [A Linux Dev Environment on Windows with WSL 2, Docker Desktop](https://nickjanetakis.com/blog/a-linux-dev-environment-on-windows-with-wsl-2-docker-desktop-and-more)
    - [Docker Desktop WSL 2 backend](https://docs.docker.com/docker-for-windows/wsl/)


<br>

## 安裝 Docker runtime
> 包含 Docker-compose

### 安裝資訊
- [Run Docker in WSL2 in 5 minutes (via systemd, without Docker Desktop!)](https://dev.to/klo2k/run-docker-in-wsl2-in-5-minutes-via-systemd-without-docker-desktop-28gi)

### trouble shooting
- ### error getting credentials - err: exec: "docker-credential-desktop.exe": executable file not found in $PATH, out: ``
    ```
    $ docker-compose up
    [+] Running 0/0
     ⠋ llm_iambackend Pulling            0.0s
     ⠋ llamacpp_server Pulling           0.0s
     ⠋ llm_portal Pulling                0.0s
     ⠋ llm_nginx Pulling                 0.0s
    error getting credentials - err: exec: "docker-credential-desktop.exe": executable file not found in $PATH, out: ``
    ```
    - solution
        - [Docker-credential-desktop.exe executable file not found in $PATH using wsl2](https://forums.docker.com/t/docker-credential-desktop-exe-executable-file-not-found-in-path-using-wsl2/100225/5)
            ```
            In ~/.docker/config.json change credsStore to credStore
            ```
            ![](https://hackmd.io/_uploads/rJnqOvbD6.png)

<br>

## 在新版 Ubuntu 上，安裝常用軟體
```bash
# 安裝 tree
sudo apt update; apt install -y tree

# 安裝 Miniconda3
$ curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
$ bash Miniconda3-latest-Linux-x86_64.sh

# 註冊 conda 路徑：
$ conda list
conda: command not found

$ nano ~/.bashrc
# 2021.12.02, miniconda
PATH="$PATH:/home/tj/miniconda3/bin"

$ source ~/.bashrc
# 或是開新的 terminal 就生效
```
- [[HackMD] 安裝 node 指令](https://hackmd.io/ioPaKTHcTVOkDyJXraPYLA?both#如何在-Ubuntu-上安裝-node-指令-Nodejs-≥-20-？)


<br>

## 參考資料
- ### [[推薦] WSL (Windows Subsystem for Linux) 安裝與使用教學](https://xenby.com/b/226-推薦-wsl-windows-subsystem-for-linux-安裝與使用教學)
- ### [在 Windows 10 環境上安裝 WSL 2](https://www.huanlintalk.com/2020/02/wsl-2-installation.html)
- ### [比較 WSL 1 和 WSL 2](https://docs.microsoft.com/zh-tw/windows/wsl/compare-versions)

<br>

## 討論
### wsl 要如何更新 ubuntu？現況：ubuntu20.04，想要升到最新
- ### 建議解法
    - 如果只是用 python 或 conda，建議直接裝最新的

- ### gpt-5.4 (2026/04/17)
    可以，但 **不建議直接硬跳「最新」**。
    在 WSL 裡，**Ubuntu 20.04 通常要一版一版升**，也就是：

    `20.04 -> 22.04 -> 24.04 -> (再看是否有更新版可升)`

    而且在 WSL 環境，我會更推薦你優先考慮這兩種做法：

    1. **最穩定**：新裝一個新版 Ubuntu，再搬資料
    2. **原地升級**：20.04 先升到 22.04，再升到 24.04

    我剛剛嘗試查官方最新文件，但目前外部查詢工具異常，沒法即時驗證「此刻最新可升到哪一版」。所以以下先給你 **安全、實務上可用** 的做法；若你要，我下一則也可以幫你整理成「可直接複製貼上」版。

    ---

    ### 我建議的做法：先備份，再升級

    #### 0. 在 Windows 先確認 WSL distro 名稱

    用 PowerShell：

    ```powershell
    wsl -l -v
    ```

    你會看到類似：

    ```powershell
      NAME      STATE           VERSION
    * Ubuntu    Running         2
    ```

    假設名稱是 `Ubuntu`。

    ---

    ### 1. 先備份整個 WSL Ubuntu

    這很重要。萬一升壞，可以還原。

    在 PowerShell：

    ```powershell
    wsl --shutdown
    wsl --export Ubuntu D:\backup\ubuntu20-backup.tar
    ```

    ---

    ### 2. 先更新 WSL 本身

    在 PowerShell（建議系統管理員）：

    ```powershell
    wsl --update
    wsl --shutdown
    ```

    ---

    ### 3. 進入 Ubuntu 20.04，先把現有套件更新乾淨

    ```bash
    sudo apt update
    sudo apt full-upgrade -y
    sudo apt autoremove -y
    sudo apt autoclean
    ```

    再確認升級工具有裝：

    ```bash
    sudo apt install update-manager-core -y
    ```

    檢查設定：

    ```bash
    cat /etc/update-manager/release-upgrades
    ```

    通常要看到：

    ```ini
    Prompt=lts
    ```

    如果不是，可改成：

    ```bash
    sudo nano /etc/update-manager/release-upgrades
    ```

    改成：

    ```ini
    Prompt=lts
    ```

    ---

    ### 4. 從 20.04 升到 22.04

    ```bash
    sudo do-release-upgrade
    ```

    如果它說找不到新版本，可試：

    ```bash
    sudo do-release-upgrade -d
    ```

    但 `-d` 通常只在新版本剛開放、正式升級通道尚未全面打開時才考慮，用前要更小心。

    升完後重開 WSL：

    在 PowerShell：

    ```powershell
    wsl --shutdown
    ```

    再進 Ubuntu 檢查版本：

    ```bash
    lsb_release -a
    cat /etc/os-release
    ```

    ---

    ### 5. 再從 22.04 升到 24.04

    先再次更新乾淨：

    ```bash
    sudo apt update
    sudo apt full-upgrade -y
    sudo apt autoremove -y
    ```

    然後再跑：

    ```bash
    sudo do-release-upgrade
    ```

    升完再確認版本：

    ```bash
    lsb_release -a
    ```

    ---

    ### 更推薦的方式：直接新裝新版 Ubuntu，再搬資料

    如果你不想冒原地升級風險，這方法通常更乾淨。

    #### 作法

    在 PowerShell：

    ```powershell
    wsl --install -d Ubuntu
    ```

    或到 Microsoft Store 安裝新的 Ubuntu 發行版。

    安裝完後，在舊的 Ubuntu 裡把資料複製到 Windows 目錄，或直接透過：

    ```powershell
    \\wsl$
    ```

    去搬家。

    你也可以把舊的 Ubuntu 保留一陣子，確認新環境沒問題再刪。

    ---

    ### 什麼情況下，我會建議你「不要原地升級」

    如果你有以下情況，建議直接新裝新版：

    * 這個 WSL 環境已經用了很久，裝了很多套件
    * 有改過很多 system config
    * 有第三方 source / PPA
    * 你其實只在意開發環境與資料，不在意保留整個舊系統狀態

    ---

    ### 升級前你要特別注意

    #### 1. 第三方 PPA

    先看有沒有額外 source：

    ```bash
    ls /etc/apt/sources.list.d/
    ```

    有些 PPA 會讓升級失敗。

    #### 2. Python / Docker / Node / CUDA 類環境

    這些常常在大版本升級後要重整。

    #### 3. WSL 不等於完整 systemd Linux

    雖然現在 WSL 已較完整，但某些服務型套件升級時，表現仍可能和實體 Ubuntu 不完全一樣。

    ---

    ### 最實際的建議

    如果你是一般開發用途，我建議你選：

    **方案 A：新裝新版 Ubuntu + 搬資料**
    最乾淨、最穩。

    如果你一定要保留現有環境：

    **方案 B：20.04 -> 22.04 -> 24.04 逐步升級**
    不要直接亂改 sources 跳版本。

    ---

    ### 最後給你一個精簡版流程

    #### Windows PowerShell

    ```powershell
    wsl -l -v
    wsl --shutdown
    wsl --export Ubuntu D:\backup\ubuntu20-backup.tar
    wsl --update
    wsl --shutdown
    ```

    #### Ubuntu 20.04

    ```bash
    sudo apt update
    sudo apt full-upgrade -y
    sudo apt autoremove -y
    sudo apt install update-manager-core -y
    sudo do-release-upgrade
    ```

    #### 升到 22.04 後，再跑一次

    ```bash
    sudo apt update
    sudo apt full-upgrade -y
    sudo apt autoremove -y
    sudo do-release-upgrade
    ```

<br>

### wsl 如何切換 OS　？
- ### Question
    ```
    (base) C:\Users\User>wsl --list
    Windows 子系統 Linux 版發佈:
    Ubuntu-20.04 (預設)
    docker-desktop-data
    Ubuntu
    docker-desktop
    ```
    如何開啟 Ubuntu ??

- ### gpt-5.4 (2026/04/17)
    可以，直接這樣開。

    你現在有兩個 Ubuntu：

    * `Ubuntu-20.04`（目前預設）
    * `Ubuntu`

    所以有幾種開法。

    ### 1. 開啟預設的 Ubuntu

    你目前預設是 `Ubuntu-20.04`，所以直接輸入：

    ```powershell
    wsl
    ```

    這樣就會進入 `Ubuntu-20.04`。

    ---

    ### 2. 指定開啟某一個 Ubuntu

    #### 開 `Ubuntu-20.04`

    ```powershell
    wsl -d Ubuntu-20.04
    ```

    #### 開 `Ubuntu`

    ```powershell
    wsl -d Ubuntu
    ```

    Microsoft 的 WSL 指令支援用 `--distribution` / `-d` 指定要啟動哪個發行版。

    ---

    ### 3. 想把 `Ubuntu` 改成預設

    如果你之後希望輸入 `wsl` 就直接進 `Ubuntu`，可先設定：

    ```powershell
    wsl --set-default Ubuntu
    ```

    之後再輸入：

    ```powershell
    wsl
    ```

    就會進 `Ubuntu`。

    ---

    ### 4. 查看目前哪個是預設

    ```powershell
    wsl -l -v
    ```

    有標示「預設」的那個，就是 `wsl` 直接進去的目標。

    ---

    ### 你現在最直接可以試的

    先輸入：

    ```powershell
    wsl
    lsb_release -a
    ```

    如果你是想開新版那個 Ubuntu，輸入：

    ```powershell
    wsl -d Ubuntu
    ```


<br>

{%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}