Go 개발을 시작하기 전 겪는 흔한 난관들
새로운 프로그래밍 언어를 배우기로 결심하고 설레는 마음으로 터미널을 켰는데, “go: command not found”라는 차가운 메시지를 마주한 적이 있나요? 분명 설치 파일을 내려받아 실행한 것 같은데, 왜 컴퓨터는 Go라는 이름을 알아듣지 못하는 걸까요? 이런 경험은 Go를 처음 접하는 입문 개발자라면 누구나 한 번쯤 겪게 되는 아주 흔한 일이에요.
단순히 설치 파일을 클릭하는 것만으로 모든 준비가 끝나지 않기 때문이에요. 컴퓨터의 시스템 경로를 지정해 주는 환경 변수 설정부터, 코드를 효율적으로 작성하기 위한 편집기 연동까지 거쳐야 할 과정이 생각보다 많거든요. 이 기초적인 단계를 대충 넘기면, 나중에 패키지를 불러오거나 프로젝트를 빌드할 때마다 원인을 알 수 없는 오류 때문에 밤을 지새우게 될지도 몰라요.
Go(Golang)는 구글에서 만든 언어답게 매우 빠르고 강력한 성능을 자랑하지만, 그 강력함을 제대로 누리려면 올바른 개발환경 구현 방법을 숙지하는 것이 무엇보다 중요해요. 제대로 된 환경이 갖춰져 있어야 비로소 언어의 문법과 로직에만 집중할 수 있는 몰입의 시간을 가질 수 있어요.
이 글에서는 여러분이 더 이상 설치 오류 때문에 스트레스받지 않도록, 가장 깔끔하고 표준적인 Go 개발 환경 구축 과정을 안내해 드릴게요. 복잡한 이론보다는 지금 당장 내 컴퓨터에서 동작하는 실전적인 방법에 집중했어요.
이 가이드에서 배우게 될 내용
- 운영체제별 가장 안정적인 Go 설치 방법
- 실수를 줄여주는 환경 변수(PATH) 설정 노하우
- 생산성을 극대화하는 VS Code와 Go 확장 도구 연동
- 최신 표준인 Go Modules를 이용한 프로젝트 생성 및 실행
- 설치 과정에서 발생하는 대표적인 문제 해결법
설치 전 확인해야 할 준비물과 체크리스트
무작정 설치 파일을 내려받기 전에, 현재 사용 중인 컴퓨터의 상태를 먼저 점검하는 과정이 필요해요. 준비 없이 진행하다 보면 운영체제 버전이 맞지 않거나, 기존에 설치된 다른 프로그래밍 언어와 충돌이 발생하여 환경이 꼬이는 불상사가 생길 수 있거든요.
가장 먼저 확인해야 할 것은 운영체제의 아키텍처예요. 최근 대부분의 컴퓨터는 64비트(x64)를 사용하지만, Apple Silicon(M1, M2, M3 등) 칩을 사용하는 Mac의 경우에는 ARM64 버전을 선택해야 최적의 성능을 낼 수 있어요. 잘못된 아키텍처용 설치 파일을 받으면 실행 자체가 안 되거나 속도가 현저히 느려질 수 있으니 주의해야 해요.
Go 설치를 시작하기 전에 터미널(Windows는 CMD 또는 PowerShell, macOS/Linux는 Terminal)을 열어두는 습관을 들이면 좋아요. 설치가 잘 되었는지 즉시 확인하기 위해 명령어를 입력해야 하기 때문이에요.
운영체제별 설치 방식 비교
각 운영체제에 따라 권장되는 설치 방식이 달라요. 본인의 환경에 맞는 방법을 선택하여 진행해 주세요.
| 운영체제 | 권장 설치 방법 | 장점 | 난이도 |
|---|---|---|---|
| Windows | 공식 홈페이지 .msi 파일 실행 | 환경 변수 자동 설정 지원 | 매우 낮음 |
| macOS | Homebrew 이용 또는 .pkg 설치 | 버전 관리가 매우 용이함 | 낮음 |
| Linux | 시스템 제어권이 높고 가벼움 | 보통 |
사전 준비 핵심 개념
설치 과정에서 자주 등장하는 용어들을 미리 이해해 두면 훨씬 수월해요. 이 개념들은 나중에 고급 기술을 배울 때도 계속 사용되니 눈여겨보세요.
- GOROOT: Go 언어 자체가 설치된 경로를 의미해요. 우리가 직접 건드릴 일은 많지 않지만, 시스템이 Go를 어디서 찾아야 할지 알려주는 기준점이 돼요.
- GOPATH: 여러분이 작성한 코드와 다운로드한 외부 패키지들이 저장되는 작업 공간이에요. 과거에는 매우 중요했지만, 최근에는 Go Modules 덕분에 그 역할이 조금 줄어들었어요.
- PATH: 운영체제가 명령어를 실행할 때 찾아보는 경로들의 목록이에요. Go 설치 후 터미널에서 명령어가 먹히지 않는다면 대부분 이 PATH 설정에 문제가 있는 거예요.
이미 다른 프로그래밍 언어(Python, Node.js 등)를 사용하고 있다면, 환경 변수 설정 시 기존에 설정된 값들을 덮어쓰지 않도록 주의해야 해요. 반드시 기존 경로 뒤에 추가하는 방식으로 작업해야 해요.
단계별 Go 개발환경 구현 실전 가이드
이제 본격적으로 개발을 위한 환경을 만들어볼게요. 이 과정은 크게 설치, 환경 설정, 도구 연동, 그리고 첫 실행의 4단계로 나뉩니다. 천천히 하나씩 따라오시면 돼요.
STEP 1. 운영체제에 맞는 Go 설치하기
가장 먼저 Go 공식 홈페이지(go.dev)에 접속하여 설치 파일을 받아야 해요. 운영체제별로 가장 권장되는 방법은 다음과 같아요.
Windows 사용자라면: 홈페이지의 Download 메뉴에서 Windows용 .msi 파일을 내려받으세요. 파일을 실행하고 ‘Next’를 계속 누르면 설치가 진행돼요. Windows의 장점은 설치 과정에서 환경 변수(PATH)를 알아서 등록해 준다는 점이에요. 덕분에 초보자가 가장 쉽고 빠르게 시작할 수 있어요.
macOS 사용자라면: 두 가지 방법이 있어요. 첫 번째는 공식 홈페이지에서 brew install go 명령어를 사용하는 거예요. 개발자라면 패키지 관리자인 Homebrew를 사용하는 두 번째 방법을 강력히 추천해요. 나중에 Go 버전을 업데이트할 때도 명령어 한 줄로 끝낼 수 있어 매우 편리하기 때문이에요.
Linux 사용자라면: 보통 tar.gz 압축 파일을 내려받아 원하는 디렉토리에 압축을 푸는 방식을 사용해요. 예를 들어 /usr/local/go에 압축을 풀었다면, 이 경로를 시스템의 PATH에 등록해 주어야 해요. 리눅스는 사용자가 시스템을 직접 제어하는 경우가 많으므로 이 과정이 조금 더 수동적일 수 있어요.
STEP 2. 환경 변수 및 설치 확인하기
설치를 마쳤다면 컴퓨터가 Go를 제대로 인식하는지 확인해야 해요. 터미널이나 명령 프롬프트를 열고 다음 명령어를 입력해 보세요.
go version
만약 go version go1.21.x darwin/arm64와 같은 결과가 나온다면 성공이에요! 하지만 “command not found”가 뜬다면 PATH 설정이 누락된 것이에요.
Windows의 경우 ‘시스템 환경 변수 편집’ 메뉴에 들어가서 ‘Path’ 항목에 Go의 bin 폴더 경로(예: C:\Go\bin)가 포함되어 있는지 확인해야 해요. macOS나 Linux에서는 ~/.zshrc 또는 ~/.bashrc 파일을 열어 export PATH=$PATH:/usr/local/go/bin 문구를 추가해 주어야 해요. 설정을 변경한 뒤에는 반드시 터미널을 완전히 껐다가 다시 켜야 적용된다는 점을 잊지 마세요.
STEP 3. VS Code와 Go 확장 도구 연동하기
메모장에 코드를 짤 수는 없겠죠? 현대적인 개발을 위해서는 강력한 편집기가 필요해요. 저는 전 세계 개발자들이 가장 많이 사용하는 Visual Studio Code(VS Code)를 추천해요.
VS Code를 설치했다면, 왼쪽 사이드바의 확장(Extensions) 아이콘을 클릭하고 “Go”를 검색하세요. Google에서 만든 공식 확장 프로그램을 설치하면 됩니다. 설치가 완료되면 VS Code가 Go 개발을 돕기 위해 여러 도구를 추가로 설치하겠느냐고 물어볼 거예요. 이때 오른쪽 하단에 뜨는 Install All 버튼을 꼭 눌러주세요. 이 과정에서 자동 완성(IntelliSense), 코드 포맷팅, 디버깅 도구 등이 함께 설치되어 개발 환경이 비약적으로 업그레이드돼요.
STEP 4. Go Modules를 이용한 프로젝트 생성
과거에는 코드를 반드시 특정 폴더(GOPATH) 안에만 만들어야 하는 불편함이 있었지만, 지금은 Go Modules라는 시스템 덕분에 컴퓨터 어디에서든 자유롭게 프로젝트를 만들 수 있어요. 이 방식이 현재의 표준이므로 반드시 익혀두어야 해요.
먼저 원하는 위치에 새 폴더를 만들고 해당 폴더로 이동한 뒤, 터미널에 다음 명령어를 입력하세요.
go mod init my-project
이 명령어를 실행하면 폴더 안에 go.mod라는 파일이 생성돼요. 이 파일은 이 프로젝트가 어떤 Go 버전을 사용하는지, 어떤 외부 라이브러리에 의존하고 있는지를 기록하는 프로젝트의 ‘설계도’ 역할을 해요. 이제 여러분은 독립적인 프로젝트를 운영할 준비가 된 거예요.
STEP 5. 첫 번째 프로그램 작성 및 실행하기
이제 모든 준비가 끝났어요. 마지막으로 실제로 코드가 돌아가는지 확인해 볼 차례예요. 프로젝트 폴더에 main.go라는 파일을 만들고 아래 코드를 그대로 복사해서 붙여넣어 보세요.
package main
import "fmt"
func main() {
fmt.Println("Hello, Go World!")
}
코드를 저장했다면 터미널에서 다음 명령어를 입력해 실행해 보세요.
go run main.go
터미널에 “Hello, Go World!”라는 문구가 찍혔다면, 여러분은 방금 완벽한 Go 개발 환경을 구현해낸 거예요! 축하드려요. 이제 여러분은 Go라는 강력한 도구를 사용할 모든 권한을 얻었습니다.
실전 개발 환경 요약 일정표
처음부터 모든 것을 완벽하게 하려고 하기보다, 아래 순서대로 하나씩 완료해 나가는 것을 목표로 하세요.
- 운영체제 확인 및 Go 설치 파일 다운로드 (10분)
- 설치 완료 후 터미널에서 버전 확인 (5분)
- VS Code 설치 및 Go 확장 프로그램 설치 (15분)
- Go 도구(Tools) 자동 설치 대기 (10분)
- 프로젝트 폴더 생성 및 go mod init 실행 (5분)
- Hello World 코드 작성 및 실행 (5분)
자주 하는 실수와 해결법
환경 구축 과정은 예상치 못한 오류로 가득할 수 있어요. 당황하지 말고 아래 사례들을 참고해 보세요.
- ❌ “go: command not found” 오류가 발생해요
왜 발생하는가: Go가 설치되었더라도 운영체제의 PATH 경로에 Go 실행 파일 위치가 등록되지 않았기 때문이에요.
✅ 해결법: 운영체제의 환경 변수 설정에서 Go의 bin 폴더 경로를 PATH에 추가하고, 터미널을 완전히 재시작하세요. - ❌ VS Code에서 자동 완성이 작동하지 않아요
왜 발생하는가: Go 확장 프로그램은 설치했지만, 내부적으로 필요한 분석 도구(gopls 등)가 설치되지 않았을 확률이 높아요.
✅ 해결법: VS Code 명령 팔레트(Ctrl+Shift+P)를 열고 “Go: Install/Update Tools”를 입력한 뒤, 모든 항목을 선택해 설치하세요. - ❌ go.mod 파일이 없다는 에러가 떠요
왜 발생하는가: 프로젝트 폴더 내에서 모듈 초기화를 하지 않고 코드를 실행하려고 했기 때문이에요.
✅ 해결법: 해당 폴더 터미널에서go mod init [프로젝트이름]을 실행하여 모듈 파일을 생성하세요. - ❌ 패키지를 불러올 때 빨간 줄이 생겨요
왜 발생하는가: 외부 라이브러리를 다운로드하지 않았거나, 모듈 경로가 일치하지 않기 때문이에요.
✅ 해결법:go mod tidy명령어를 입력하여 사용 중인 패키지를 정리하고 필요한 의존성을 자동으로 내려받으세요. - ❌ macOS에서 설치했는데 명령어가 안 먹혀요
왜 발생하는가: 설치 경로는 맞지만, 현재 사용 중인 쉘(zsh 또는 bash)의 설정 파일에 경로가 반영되지 않았기 때문이에요.
✅ 해결법:~/.zshrc파일에 PATH 설정을 추가하고source ~/.zshrc를 입력하세요.
자주 묻는 질문
Q. Go를 설치할 때 GOROOT와 GOPATH 중 무엇을 더 신경 써야 하나요?
최근에는 Go Modules 방식이 표준이기 때문에 GOPATH를 직접 관리할 일은 거의 없어요. 다만, Go 언어 자체의 위치인 GOROOT는 시스템이 Go를 찾는 기준이 되므로 설치 시 제대로 설정되었는지만 확인하면 돼요.
Q. Go 버전을 업데이트하려면 어떻게 해야 하나요?
Windows는 기존 버전을 지우고 새 버전을 설치하는 것이 가장 깔끔해요. macOS에서 Homebrew를 쓴다면 brew upgrade go 한 줄이면 끝납니다. Linux는 기존 압축 파일을 삭제하고 새 버전을 다시 압축 해제하면 돼요.
Q. VS Code 말고 다른 편집기를 써도 괜찮을까요?
물론이에요. JetBrains사의 GoLand는 유료이지만 매우 강력한 기능을 제공하며, Vim이나 Emacs를 사랑하는 숙련된 개발자들도 Go 환경을 잘 구축해서 사용하고 있어요. 하지만 입문자에게는 VS Code가 가장 배우기 쉽고 커뮤니티 지원이 풍부해요.
Q. Go는 Windows에서도 성능이 잘 나오나요?
네, 당연합니다! Go는 처음부터 클라우드와 서버 환경을 염두에 두고 설계되었기 때문에, Windows 환경에서도 매우 안정적이고 빠른 성능을 보여줍니다. 윈도우 환경에서 개발하더라도 나중에 리눅스 서버로 배포할 때 큰 어려움이 없도록 설계되어 있어요.
Q. 공부를 시작하기에 가장 좋은 순서는 무엇인가요?
환경 구축이 끝났다면, 우선 기본 문법(변수, 조건문, 반복문)을 익히고 바로 Go의 핵심인 Goroutine(고루틴)과 인터페이스 개념으로 넘어가시는 것을 추천해요.
완벽한 시작을 위한 마지막 정리
Go 개발환경을 구축하는 과정이 처음에는 조금 생소하고 복잡하게 느껴졌을 수도 있어요. 하지만 이 과정을 한 번만 제대로 거치고 나면, 앞으로의 학습 속도는 비약적으로 빨라질 거예요. 환경 설정은 개발의 기초 공사와 같아서, 단단하게 지어놓아야 그 위에 멋진 프로그램을 쌓아 올릴 수 있거든요.
- 운영체제 아키텍처(x64 vs ARM64)에 맞는 설치 파일 선택하기
- 설치 후 반드시
go version으로 정상 작동 확인하기 - VS Code 설치 후 Go 확장 프로그램 및 도구(Tools) 모두 설치하기
- 모든 프로젝트는
go mod init으로 시작하기 - 오류 발생 시 가장 먼저 PATH와 모듈 상태 점검하기
다음 단계로 나아가기
환경 구축을 마쳤다면 이제 멈춰있지 말고 바로 움직여 보세요. 다음 단계를 추천해 드릴게요.
- 오늘 할 일: 작성한 Hello World 코드를 다양한 위치에서 실행해 보며 모듈 개념 익히기
- 이번 주 할 일: Go의 기본 자료형과 제어문(if, for)을 활용해 간단한 계산기 만들기
- 실행 직전 할 일: Go 공식 문서(go.dev/doc)의 ‘Tutorial’ 섹션 하나를 골라 끝까지 따라 해보기
Go는 배울수록 그 간결함과 강력함에 매료되는 언어예요. 여러분의 첫 번째 Go 프로젝트가 성공적으로 돌아가는 그날까지 응원하겠습니다. 더 깊이 있는 Go 프로그래밍 기술이 궁금하다면, 저희가 준비한 다른 시리즈 글들도 함께 읽고 실력을 완성해 보세요!
관련 시리즈 글도 함께 읽고 실력을 완성하세요: /programming/golang/go-install-setup-complete-guide/
