Visual Studio Code에서 Python 개발 환경을 구성하려면 Python Extension 설치가 필수입니다. 평소에는 마켓플레이스에서 바로 설치하면 되지만, 인터넷이 차단된 사내망이나 보안이 중요한 폐쇄망에서는 이야기가 다릅니다. 이럴 때는 .vsix 파일을 미리 다운로드해 오프라인으로 설치해야 하며, 방법 자체는 어렵지 않습니다. 인터넷이 되는 PC에서 확장 프로그램 파일만 받아 이동식 저장장치로 옮긴 뒤, VS Code의 명령 팔레트에서 몇 번 클릭하면 설치가 완료됩니다.
Python 확장 오프라인 설치는 왜 필요할까
대부분의 개발 환경은 인터넷에 연결되어 있어 VS Code 좌측 확장 아이콘에서 Python을 검색해 바로 설치할 수 있습니다. 하지만 실제 업무 현장에서는 보안 정책상 외부 네트워크 접속이 차단된 경우가 많습니다. 특히 공공기관, 금융권, 대기업 사내망에서 개발 업무를 할 때 이런 상황이 자주 발생합니다.
오프라인 설치는 인터넷이 되는 PC에서 필요한 확장 프로그램 파일을 내려받아 USB나 이메일 등으로 옮긴 뒤, 대상 PC에서 직접 설치하는 방식입니다. 이때 사용하는 파일이 바로 .vsix 형식입니다. VS Code 확장 프로그램은 모두 이 형식으로 배포되며, 오프라인 설치는 이 파일을 지정해 주는 것만으로 끝납니다.
오프라인 설치 전에 준비할 것들
설치를 시작하기 전에 필요한 준비물을 정리하면 다음과 같습니다.
- VS Code 설치: 대상 PC에 Visual Studio Code가 설치되어 있어야 합니다. 설치가 안 되어 있다면 공식 사이트에서 인스톨러를 받아 미리 설치해 두세요.
- Python 확장 .vsix 파일: 인터넷이 되는 PC에서 마켓플레이스에 접속해 다운로드합니다.
- Python 런타임: Python 코드를 실제로 실행하려면 Python 인터프리터가 필요합니다. 공식 사이트에서 설치 파일을 받아 대상 PC에 미리 설치해 두는 것이 좋습니다.
이 중에서 .vsix 파일을 받는 과정이 핵심인데, 방법은 다음과 같습니다.
- Visual Studio Marketplace(marketplace.visualstudio.com)에 접속합니다.
- 상단 검색창에서
Python을 검색합니다. - Microsoft가 배포하는 Python 확장을 클릭합니다.
- 페이지 우측에서 Download Extension 버튼을 찾아 클릭합니다.
.vsix파일이 내려받아집니다. 이 파일을 USB 등에 복사해 대상 PC로 옮깁니다.
이때 주의할 점은 확장 프로그램 버전입니다. 받는 시점에 따라 버전이 다를 수 있는데, 대상 PC에 설치된 VS Code 버전과 호환되는지 확인할 필요는 없습니다. VS Code는 대부분의 최신 확장을 지원하므로 큰 문제가 되지 않습니다.
VS Code에서 .vsix 파일로 설치하는 단계
이제 준비된 .vsix 파일을 대상 PC에서 설치해 보겠습니다. 전체 과정은 3단계로 짧습니다.
1단계: 명령 팔레트 열기
대상 PC에서 VS Code를 실행하고, 키보드에서 Ctrl + Shift + P를 눌러 명령 팔레트를 엽니다. macOS를 사용 중이라면 Cmd + Shift + P입니다.
2단계: Install from VSIX 선택
명령 팔레트 입력창에 Install from VSIX라고 입력합니다. 검색 결과에 Extensions: Install from VSIX... 항목이 나타나면 이를 선택합니다.
3단계: 파일 선택 및 설치 완료 확인
파일 탐색기 창이 열리면 아까 옮겨둔 .vsix 파일을 선택합니다. 설치가 진행되고, 완료되면 VS Code 우측 하단에 알림이 표시됩니다. 좌측 확장 탭에서 Python이 설치된 목록에 포함되어 있는지 확인하면 끝입니다.
설치 후에는 확장이 정상 작동하는지 간단한 Python 파일을 열어 확인해 보는 것을 권장합니다. 코드 편집기에서 색상 강조나 자동 완성이 동작하면 정상적으로 설치된 것입니다.
설치 후 필수 설정 언어 서버와 인터프리터 지정
확장 설치는 끝났지만, 실제로 Python 개발을 시작하려면 몇 가지 설정을 확인해야 합니다. 특히 Pylance 언어 서버와 Python 인터프리터 경로가 제대로 지정되어 있어야 IntelliSense(자동 완성), 코드 분석, 디버깅 기능이 원활하게 동작합니다.
먼저 언어 서버 설정입니다. VS Code에서 Ctrl + ,(쉼표)를 눌러 설정 창을 열고, 검색창에 Python: Language Server를 입력합니다. 기본값은 Pylance로 설정되어 있는데, 이 상태를 유지하면 됩니다. Pylance는 Microsoft가 Python 확장과 함께 제공하는 언어 서버로, 빠른 속도와 정확한 타입 검사를 지원합니다.
다음으로 Python 인터프리터 경로입니다. VS Code 하단 상태 표시줄에 Python 버전이 표시되는데, 이를 클릭하면 사용 가능한 인터프리터 목록이 나타납니다. 시스템에 설치된 Python이나 가상 환경을 선택하면 됩니다. 만약 특정 프로젝트에서 가상 환경을 사용 중이라면 Python: Python Path 설정에서 해당 경로를 직접 지정할 수도 있습니다.
| 설정 항목 | 기본값 | 변경 시점 |
|---|---|---|
| Python: Language Server | Pylance | 특별한 이유가 없으면 유지 |
| Python: Python Path | 시스템 Python | 가상 환경 사용 시 변경 |
오프라인 설치 시 자주 겪는 문제와 해결 방법
오프라인 설치는 과정이 단순하지만, 가끔 예상치 못한 문제가 발생하기도 합니다. 몇 가지 상황별 대처 방법을 정리했습니다.
확장이 설치 목록에 보이는데 동작하지 않는 경우
Python 확장이 설치된 것으로 표시되는데 코드 편집 기능이 작동하지 않는다면, 인터프리터가 선택되지 않았을 가능성이 높습니다. 하단 상태 표시줄의 Python 버전을 확인하고, 아무것도 선택되어 있지 않다면 인터프리터를 지정해 주세요.
.vsix 파일이 손상되었다는 메시지가 나오는 경우
파일을 USB로 옮기는 과정에서 손상될 수 있습니다. 다시 다운로드하거나, 파일 크기를 원본과 비교해 보세요. 시장에서는 대부분 30～70MB 수준입니다.
설치 버튼이 비활성화되어 있는 경우
관리자 권한이 없는 계정으로 VS Code를 실행했을 때 발생할 수 있습니다. VS Code를 관리자 권한으로 실행한 뒤 다시 시도해 보세요.
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 설치는 됐는데 동작 안 함 | 인터프리터 미지정 | 상태 표시줄에서 Python 버전 선택 |
| 파일 손상 메시지 | 전송 중 손상 | 재다운로드 후 재시도 |
| 설치 버튼 비활성화 | 권한 부족 | 관리자 권한으로 VS Code 실행 |
오프라인 설치는 확장 프로그램 하나만 되는 걸까
Python 확장만 오프라인 설치가 가능한 것은 아닙니다. VS Code 마켓플레이스에서 제공되는 모든 확장 프로그램은 동일한 방식으로 .vsix 파일을 내려받아 오프라인 설치할 수 있습니다. 예를 들어 한글 팩, Git 관련 확장, Jupyter 등도 같은 절차로 설치하면 됩니다.
특히 폐쇄망에서 개발 환경을 구축해야 한다면, 필요한 확장 프로그램 목록을 미리 정리해 두는 것이 좋습니다. 인터넷이 되는 PC에서 한 번에 여러 개의 .vsix 파일을 받아 USB에 보관해 두면, 나중에 동일한 환경을 빠르게 구성할 수 있습니다.
FAQ
Q. Python 확장을 오프라인으로 설치하려면 인터넷이 아예 필요 없나요?
인터넷이 되는 PC에서 .vsix 파일을 한 번 받아 두면, 이후 대상 PC에서는 인터넷 없이 설치할 수 있습니다. 다만 Python 인터프리터 자체도 설치되어 있어야 코드 실행이 가능합니다.
Q. Download Extension 버튼이 안 보이는데 어떻게 하나요?
마켓플레이스 페이지에서 확장 프로그램 상세 화면 우측에 Resources 섹션이 있습니다. 여기에 Download Extension 링크가 있습니다. 페이지가 오래된 경우 브라우저를 새로고침하거나 다른 브라우저로 접속해 보세요.
Q. VS Code 버전이 낮으면 최신 Python 확장이 설치되나요?
대부분의 경우 문제없이 설치되지만, 아주 오래된 VS Code 버전에서는 최신 확장과 호환되지 않을 수 있습니다. 가능하면 VS Code를 최신 버전으로 업데이트한 뒤 설치하는 것이 안전합니다.
Q. 설치한 확장을 다른 PC에 복사해서 써도 되나요?
.vsix 파일 자체를 복사해서 쓰는 것은 문제없습니다. 다만 각 PC에 VS Code가 설치되어 있어야 하며, 확장 프로그램 버전이 VS Code 버전과 호환되어야 합니다.