설치

빠른 설치 (5분)

# Go 1.25+ 설치 후:
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
wails3 doctor  # 설치 확인

wails3 doctor가 통과하면 설치가 완료된 것입니다. 첫 번째 앱으로 건너뛰기 →

단계별 설치

Go 설치 (필수)

Wails는 Go 1.25 이상이 필요합니다.
go.dev/dl 에서 Windows 설치 프로그램을 다운로드하여 실행하세요.
설치 확인:
Terminal window
go version # 1.25 이상이어야 함
PATH 확인:
Terminal window
$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }
결과가 비어 있다면, C:\Users\YourName\go\bin을 PATH에 추가하세요.
옵션 1: 공식 설치 프로그램
go.dev/dl 에서 macOS 설치 프로그램(.pkg 파일)을 다운로드하여 실행하세요.
옵션 2: Homebrew
Terminal window
brew install go
설치 확인:
Terminal window
go version # 1.25 이상이어야 함 echo $PATH | grep go/bin # ~/go/bin이 표시되어야 함
~/go/bin이 PATH에 없다면, ~/.zshrc 또는 ~/.bash_profile에 추가하세요:
Terminal window
export PATH=$PATH:~/go/bin
옵션 1: 공식 Tarball
go.dev/dl 에서 Linux tarball을 다운로드한 후:
Terminal window
sudo rm -rf /usr/local/go sudo tar -C /usr/local -xzf go1.25.linux-amd64.tar.gz
옵션 2: 패키지 관리자
Terminal window
# Ubuntu/Debian sudo apt install golang-go # Fedora sudo dnf install golang # Arch sudo pacman -S go
PATH에 추가 (~/.bashrc 또는 ~/.zshrc에 추가):
Terminal window
export PATH=$PATH:/usr/local/go/bin:~/go/bin source ~/.bashrc # 다시 로드
확인:
Terminal window
go version echo $PATH | grep go/bin
플랫폼 종속성 설치
WebView2 런타임 (일반적으로 사전 설치됨)
Windows 10/11에는 WebView2가 기본적으로 포함되어 있습니다. 누락된 경우:
- Microsoft에서 다운로드
- 또는 나중에 wails3 doctor를 실행하면 안내에 따라 설치할 수 있습니다.
이것으로 끝! 다른 종속성은 필요하지 않습니다.
프로젝트를 저장하기 위해 Dev Drive 사용을 고려하세요. Dev Drive는 개발자 워크로드에 최적화되어 있으며 빌드 시간과 디스크 접근 속도를 최대 30%까지 향상시킬 수 있습니다.
Xcode 명령줄 도구 (필수)
Terminal window
xcode-select --install
나타나는 대화 상자에서 “Install”을 클릭하세요.
확인:
Terminal window
xcode-select -p # /Library/Developer/CommandLineTools가 표시되어야 함
이것으로 끝! macOS에는 WebKit가 기본적으로 포함되어 있습니다.
빌드 도구 및 WebKit
Wails v3은 WebKitGTK 4.1 (libsoup3 사용)이 필요합니다. 4.0만 제공하는 이전 배포판 — Ubuntu 20.04, Debian 11, RHEL 8/9 및 그 파생 버전 — 은 지원되지 않습니다.
Ubuntu/Debian
Fedora
Arch
openSUSE
Gentoo
NixOS
기타
Ubuntu 22.04+ 또는 Debian 12+가 필요합니다.
Terminal window
sudo apt update sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
Terminal window
sudo dnf install gcc pkg-config gtk3-devel webkit2gtk4.1-devel
Terminal window
sudo pacman -S base-devel gtk3 webkit2gtk-4.1
Terminal window
sudo zypper install gcc pkg-config gtk3-devel webkit2gtk3-devel
Terminal window
sudo emerge --ask net-libs/webkit-gtk:4.1
shell.nix 또는 devShell에 추가하세요:
buildInputs = with pkgs; [ webkitgtk_4_1 gtk3 pkg-config gcc ];
Wails 설치 후 wails3 doctor를 실행하세요. 배포판에 필요한 정확한 패키지가 표시됩니다.
Wails는 실험적인 GTK4 / WebKitGTK 6.0 지원도 제공합니다. GTK4로 빌드하려면 배포판에 대한 추가 종속성을 설치하고 wails3 build -tags gtk4로 빌드하세요. 자세한 내용은 Linux Packaging - GTK4를 참조하세요.
Wails CLI 설치
Terminal window
```
go install github.com/wailsapp/wails/v3/cmd/wails3@latest
```
이 명령은 wails3 명령을 ~/go/bin(Windows의 경우 %USERPROFILE%\go\bin)에 설치합니다.

설치 확인

wails3 doctor

예상 출력 (또는 유사한 내용):

Wails (v3.0.0-dev)  Wails Doctor

# System

┌──────────────────────────────────────────────────┐
| Name          | MacOS                            |
| Version       | 26.0                             |
| ID            | 25A354                           |
| Branding      | MacOS 26.0                       |
| Platform      | darwin                           |
| Architecture  | arm64                            |
| Apple Silicon | true                             |
| CPU           | Apple M2 Pro                     |
| CPU 1         | Apple M2 Pro                     |
| CPU 2         | Apple M2 Pro                     |
| GPU           | 16 cores, Metal Support: Metal 4 |
| Memory        | 16 GB                            |
└──────────────────────────────────────────────────┘

# Build Environment

┌─────────────┬─────────────────┐
| Wails CLI   | v3.0.0-alpha.40 |
| Go Version  | go1.24.6        |
└─────────────┴─────────────────┘

# Dependencies

┌─────────────────┬─────────────────────────────────────────────────┐
| npm             | 11.6.2                                          |
| *NSIS           | Not Installed. Install with `brew install...`.  |
| Xcode cli tools | 2412                                            |
└─────────────────┴─────────────────────────────────────────────────┘

# Checking for issues

SUCCESS No issues found

# Diagnosis

SUCCESS Your system is ready for Wails development!

npm 설치 (선택 사항이지만 권장)

대부분의 Wails 템플릿은 프론트엔드 도구로 npm을 사용합니다.
nodejs.org에서 다운로드하여 설치 프로그램을 실행하세요.
확인:
Terminal window
npm --version
옵션 1: 공식 설치 프로그램 nodejs.org에서 다운로드
옵션 2: Homebrew
Terminal window
brew install node
확인:
Terminal window
npm --version
옵션 1: NodeSource
Terminal window
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs # Ubuntu/Debian
옵션 2: 패키지 관리자
Terminal window
sudo dnf install nodejs # Fedora sudo pacman -S nodejs npm # Arch
확인:
Terminal window
npm --version
pnpm, yarn 또는 bun을 선호하시나요? 문제없습니다! 프로젝트의 Taskfile.yml을 업데이트하여 원하는 도구를 사용하세요.

문제 해결

`wails3` 명령을 찾을 수 없음

원인: ~/go/bin(또는 Windows의 %USERPROFILE%\go\bin)이 PATH에 없습니다.

해결 방법:

Windows
macOS/Linux

“환경 변수”를 엽니다(시작 메뉴에서 검색)
“사용자 변수”에서 Path를 찾습니다
“편집” → “새로 만들기”를 클릭합니다
추가: C:\Users\YourName\go\bin(YourName을 바꾸세요)
모든 대화 상자에서 “확인”을 클릭합니다
터미널 재시작

확인:

$env:PATH -split ';' | Where-Object { $_ -like '*\go\bin' }

~/.zshrc(macOS) 또는 ~/.bashrc(Linux)에 추가:

export PATH=$PATH:~/go/bin

재로드:

source ~/.zshrc  # 또는 ~/.bashrc

확인:

echo $PATH | grep go/bin
wails3 version

`wails3 doctor`에서 누락된 종속성 보고

Linux: 출력에 설치해야 할 패키지가 정확히 표시됩니다. 예:

❌ webkit2gtk를 찾을 수 없음
   설치 명령: sudo apt install libwebkit2gtk-4.1-dev

Windows: WebView2가 없는 경우:

Microsoft에서 다운로드
또는 첫 번째 앱 실행 시 자동으로 설치됩니다

macOS: Xcode 도구가 없는 경우:

xcode-select --install

Go 버전이 너무 오래됨

Wails v3에는 Go 1.25+가 필요합니다. 이전 버전이 있는 경우:

Windows/macOS
Linux

go.dev/dl에서 최신 버전을 다운로드하고 재설치합니다.

go.dev/dl에서 최신 tarball을 다운로드한 후:

sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.linux-amd64.tar.gz

개발 버전 (Bleeding Edge)

최신 개발 브랜치에서 가장 최신 코드를 사용하고 싶으신가요? 이를 통해 릴리스되기 전에 새로운 기능과 수정 사항을 사용할 수 있지만, 버그와 중단 변경(breaking changes)의 위험이 따릅니다. 기여자나 다가오는 기능을 테스트해야 하는 사람에게만 권장됩니다.

git clone https://github.com/wailsapp/wails.git
cd wails
git checkout v3
cd v3/cmd/wails3
go install

다음 단계

설치 완료! 시스템이 Wails 개발을 위해 준비되었습니다.

첫 번째 앱 빌드하기

10분 안에 작동하는 애플리케이션을 만드세요.

첫 번째 앱 튜토리얼 →

템플릿 탐색하기

기본으로 제공되는 항목을 확인하세요.

wails3 init -l  # 템플릿 목록

문제가 있으신가요? Discord에서 질문하거나 이슈를 열기하세요.

설치