Python

4. 윈도우에서 파이썬 사용하기

이 문서는 Microsoft 윈도우에서 파이썬을 사용할 때 알아야 할 윈도우 특정 동작에 대한 개요를 제공하는 것을 목표로 합니다.

대부분의 유닉스 시스템 및 서비스와 달리, Windows는 시스템 지원 파이썬 설치를 포함하지 않습니다. 대신 파이썬은 CPython 팀을 포함한 여러 배포처에서 제공받을 수 있습니다. 각 파이썬 배포판은 고유한 장단점이 있지만, 사용 중인 다른 도구들과의 일관성은 일반적으로 큰 이점이 됩니다. 여기에서 설명하는 절차를 진행하기 전에 기존에 사용하는 도구들이 파이썬을 직접 제공하는지 먼저 확인해 보시길 권장합니다.

CPython 팀에서 제공하는 파이썬을 받으려면 Python Install Manager를 사용하십시오. 이는 Windows 머신에서 파이썬을 글로벌 명령어로 사용할 수 있게 하고, 시스템과 통합되며, 시간이 지남에 따라 업데이트를 지원하는 독립형 도구입니다. Python Install Manager는 python.org/downloads 또는 Microsoft Store app 을 통해 다운로드할 수 있습니다.

Python Install Manager를 설치하면 모든 터미널에서 전역 python 명령을 사용하여 현재 최신 버전의 파이썬을 실행할 수 있습니다. 이 버전은 다른 버전을 추가하거나 제거함에 따라 변동될 수 있으며, py list 명령을 통해 현재 어떤 버전이 활성화되어 있는지 확인할 수 있습니다.

일반적으로 각 프로젝트마다 가상 환경 를 생성하고 터미널에서 <env>\Scripts\Activate 을 실행하여 사용하는 것을 권장합니다. 이는 프로젝트 간의 격리성을 제공하고, 시간 흐름에 따른 일관성을 보장하며, 패키지에서 추가하는 명령어도 세션 내에서 사용 가능하도록 합니다. python -m venv <env path> 를 사용하여 가상 환경을 생성하세요.

python 또는 py 명령이 제대로 작동하지 않는 경우에는 아래의 Troubleshooting 섹션을 참조하십시오. PC 구성을 위해 추가적인 수동 단계가 필요한 경우가 있습니다.

Python Install Manager를 사용하는 것 외에도 파이썬을 NuGet 패키지로 제공받을 수 있습니다. 이 패키지에 대한 자세한 정보는 아래의 nuget.org 패키지 을 참조하십시오.

임베디드용 배포판(embeddable distros)은 더 큰 애플리케이션에 내장하기 적합한 파이썬의 최소 패키지입니다. 이들은 Python Install Manager를 통해 설치할 수 있습니다. 해당 패키지에 대한 자세한 정보는 아래의 내장 가능한 패키지 을 참조하십시오.

4.1. Python Install Manager

4.1.1. 설치

Python Install Manager는 Microsoft Store app 에서 설치하거나 python.org/downloads 에서 다운로드하여 설치할 수 있습니다. 두 버전은 동일합니다.

Store를 통해 설치하려면 “설치”를 클릭하십시오. 설치가 완료되면 터미널을 열고 python 을 입력하여 시작하십시오.

To install the file downloaded from python.org, either double-click and select “Install”, or run Add-AppxPackage <path to MSIX> in Windows Powershell.

설치가 완료되면 python, py, pymanager 명령을 사용할 수 있습니다. 기존에 설치된 파이썬이 있거나 PATH 변수를 수정한 경우 해당 항목을 제거하거나 변경 사항을 되돌려야 할 수도 있습니다. 작동하지 않는 명령을 해결하는 데 관한 자세한 내용은 문제 해결 을 참조하십시오.

런타임을 처음 설치할 때, 디렉터리를 PATH 에 추가하라는 메시지가 표시될 수 있습니다. py 명령을 사용하는 것을 선호한다면 이는 선택 사항이지만, 모든 별칭(예: python3.14.exe)이 활성화되기를 원하는 경우에는 유용합니다. 해당 디렉터리는 기본적으로 %LocalAppData%\Python\bin 이나 관리자에 의해 사용자 정의될 수 있습니다. 경로를 추가하려면 ‘시작’을 클릭하고 “사용자 계정의 환경 변수 편집”을 검색하여 시스템 설정 페이지로 이동하십시오.

설치하는 각 파이썬 런타임은 스크립트를 위한 전용 디렉터리를 가집니다. 이들을 사용하려면 해당 디렉터리도 PATH 에 추가해야 합니다.

Python Install Manager는 새 버전이 출시되면 자동으로 업데이트됩니다. 이는 설치된 파이썬 런타임에 영향을 주지 않습니다. 또한 Python Install Manager를 제거하더라도 설치된 파이썬 런타임이 삭제되지 않습니다.

사용 환경에 따라 MSIX를 설치할 수 없는 경우(예: 이를 지원하지 않는 자동 배포 소프트웨어를 사용하거나, 대상이 Windows Server 2019인 경우)는 아래의 고급 설치 을 참조하십시오.

4.1.2. 기본 사용법

파이썬을 실행하기 위한 권장 명령은 python 입니다. 이 명령은 실행되는 스크립트에서 요구하는 버전, 활성화된 가상 환경 또는 별도 설정이 없는 경우 설치된 기본 버전(대개 최신 안정 버전)을 실행합니다. 특정 버전 요청이 없고 설치된 런타임이 전혀 없는 경우에는 현재 최신 릴리스가 자동으로 설치됩니다.

여러 런타임 버전이 포함된 모든 시나리오에서 권장되는 명령은 py 입니다. 이 명령은 python 또는 이전의 py.exe 런처를 대신하여 어디서든 사용할 수 있습니다. 기본적으로 py 는 python 과 동일하게 동작하지만, 명령줄 옵션을 통해 특정 버전을 선택하거나 설치를 관리하는 하위 명령을 사용할 수도 있습니다. 자세한 내용은 아래에 설명되어 있습니다.

py 명령이 이전 버전에 의해 이미 점유되어 있을 수 있으므로, 모호하지 않은 pymanager 명령도 제공됩니다. Python Install Manager를 사용하도록 설계된 스크립트 설치의 경우, 기존 설치와 충돌할 가능성이 낮으므로 pymanager 를 사용하는 것을 권장합니다. 두 명령의 유일한 차이점은 인자 없이 실행할 때 발생하며, py 는 기본 인터프리터를 실행하고 pymanager 는 도움말을 표시합니다(pymanager exec ... 는 py ... 와 동일하게 동작합니다).

이 명령어들은 콘솔 창을 생성하지 않는 윈도우 버전인 pyw, pythonw 및 pywmanager``를 포함합니다. 또한 ``python 명령어를 모방하는 python3 명령어가 포함되어 있습니다. 이는 윈도우에서 일반적인 POSIX 명령어를 실수로 사용하는 것을 방지하기 위한 것이며, 널리 사용되거나 권장되는 것은 아닙니다.

기본 런타임을 실행하려면 python 또는 py 뒤에 런타임에 전달할 인자(스크립트 파일 또는 실행할 모듈 등)를 포함하여 실행하십시오.

$> py
...
$> python my-script.py
...
$> py -m this
...

기본 런타임은 PYTHON_MANAGER_DEFAULT 환경 변수 또는 구성 파일을 통해 재정의할 수 있습니다. 설정에 대한 자세한 내용은 구성 를 참조하십시오.

To launch a specific runtime, the py command accepts a -V:<TAG> option. This option must be specified before any others. The tag is part or all of the identifier for the runtime; for those from the CPython team, it looks like the version, potentially with the platform. For compatibility, the V: may be omitted in cases where the tag refers to an official release and starts with 3.

$> py -V:3.14 ...
$> py -V:3-arm64 ...

다른 배포처의 런타임은 company 를 포함해야 할 수도 있습니다. 이는 슬래시(/ 또는 \)로 태그와 구분되어야 하며, 전체 값의 임의의 접두사로 단축할 수 있습니다. PythonCore 인 경우 company 지정은 선택 사항이며, 특정 회사의 최신 릴리스를 원하는 경우 tag 지정은 선택 사항이지만 슬래시는 필수입니다.

$> py -V:Distributor\1.0 ...
$> py -V:distrib/ ...

버전이 지정되지 않았지만 스크립트 파일이 전달된 경우, 스크립트 내에 셔뱅(shebang) 줄이 있는지 확인합니다. 셔뱅은 명령을 재정의할 수 있게 하는 파일 첫 줄의 특수한 형식입니다. 자세한 내용은 셔뱅 줄 을 참조하십시오. 셔뱅이 없거나 해석할 수 없는 경우, 스크립트는 기본 런타임으로 실행됩니다.

활성화된 가상 환경에서 실행 중이고 특정 버전을 요청하지 않았으며 셔뱅이 없는 경우, 기본 런타임은 해당 가상 환경이 됩니다. 이 시나리오에서는 python 명령이 이미 재정의되어 이러한 검사 과정이 생략되었을 가능성이 높습니다. 그럼에도 이러한 동작 방식을 통해 py 명령을 상호 교체하여 사용할 수 있습니다.

런타임이 하나도 설치되어 있지 않은 경우, 모든 실행 명령은 요청된 버전을 설치하려고 시도한 후 실행합니다. 그러나 버전이 설치된 후에는 요청된 버전이 없을 때 py exec ... 및 pymanager exec ... 명령만 설치를 진행하며, 다른 형태의 명령어는 오류를 표시하고 먼저 py install 을 사용하도록 안내합니다.

4.1.3. 명령 도움말

py help 명령은 지원되는 모든 명령과 관련 옵션의 전체 목록을 표시합니다. 어떤 명령이든 -? 옵션을 추가하여 도움말을 표시하거나, 해당 명령 이름을 py help 뒤에 넣어 확인하는 것도 가능합니다.

$> py help
$> py help install
$> py install /?

모든 명령은 공통 옵션을 지원하며, 이는 py help 에서 확인할 수 있습니다. 이 옵션들은 모든 하위 명령 뒤에 지정해야 합니다. -v 또는 --verbose 를 지정하면 출력량이 늘어나며, 디버깅을 위해 더 상세한 정보가 필요한 경우 -vv 를 사용하십시오. -q 또는 --quiet 는 출력을 줄이며, -qq 는 더욱 줄여줍니다.

--config=<PATH> ` 옵션을 사용하여 여러 설정을 한꺼번에 재정의할 수 있는 구성 파일을 지정할 수 있습니다. 이 파일들에 대한 자세한 정보는 아래의 구성 를 참조하십시오.

4.1.4. 런타임 목록

$> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]

py list``를 사용하여 설치된 런타임 목록을 볼 수 있습니다. 하나 이상의 태그(회사 지정 여부 무관) 형태로 필터를 추가할 수 있으며, 각 태그에는 범위를 제한하기 위해 ``<, <=, >= 또는 > 접두사를 포함할 수 있습니다.

A range of formats are supported, and can be passed as the --format=<FMT> or -f <FMT> option. Formats include table (a user friendly table view), csv (comma-separated table), json (a single JSON blob), jsonl (one JSON blob per result), exe (just the executable path), prefix (just the prefix path).

The --one or -1 option only displays a single result. If the default runtime is included, it will be the one. Otherwise, the “best” result is shown (“best” is deliberately vaguely defined, but will usually be the most recent version). The result shown by py list --one <TAG> will match the runtime that would be launched by py -V:<TAG>.

--only-managed 옵션은 Python Install Manager를 통해 설치되지 않은 결과는 제외합니다. 이 옵션은 py 명령을 통해 업데이트하거나 제거할 수 있는 런타임이 무엇인지 확인할 때 유용합니다.

The --online option is short for passing --source=<URL> with the default source. Passing either of these options will search the online index for runtimes that can be installed. The result shown by py list --online --one <TAG> will match the runtime that would be installed by py install <TAG>.

$> py list --online 3.14

이전 런처와의 호환성을 위해 --list, --list-paths, -0 및 -0p 명령(예: py -0p)이 유지됩니다. 이들은 추가 옵션을 허용하지 않으며 이전 형식의 출력을 생성합니다.

4.1.5. 런타임 설치

$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]

py install 을 사용하여 새로운 런타임 버전을 추가할 수 있습니다. 하나 이상의 태그를 지정할 수 있으며, 기본값을 선택하려면 특별한 태그인 default 를 사용할 수 있습니다. 설치 시 범위(Range)는 지원되지 않습니다.

--source=<URL> ` 옵션을 사용하여 런타임을 가져오는 데 사용되는 온라인 인덱스를 재정의할 수 있습니다. 이 옵션은 오프라인 설치 에 설명된 대로 오프라인 인덱스와 함께 사용할 수 있습니다.

--force 를 전달하면 캐시된 파일을 무시하고 기존 설치를 제거한 후 지정된 것으로 교체합니다.

--update 를 전달하면 새 버전이 더 최신인 경우 기존 설치를 교체합니다. 그렇지 않은 경우에는 그대로 유지됩니다. --update 와 함께 태그가 제공되지 않으면, Python 설치 관리자가 관리하는 모든 설치 항목 중 더 높은 버전이 있는 경우 모두 업데이트됩니다. 업데이트 시 전역적으로 설치된 패키지를 포함하여 설치에 가해진 모든 수정 사항이 제거되지만, 가상 환경은 계속 작동합니다.

--dry-run 을 전달하면 출력과 로그를 생성하지만, 어떤 설치도 수정하지 않습니다.

--refresh``를 전달하면 설치된 런타임에 대한 모든 등록 정보를 업데이트합니다. 이를 통해 시작 메뉴 바로가기, 레지스트리 키 및 전역 에일리어스(예: ``python3.14.exe 또는 설치된 스크립트용)를 다시 생성합니다. 이러한 정보는 런타임 설치 시 자동으로 새로 고침되지만, 패키지 설치 후에는 수동으로 새로 고쳐야 할 수도 있습니다.

위 옵션 외에도 --target 옵션을 사용하면 일반적인 설치를 수행하는 대신 지정된 디렉터리에 런타임을 추출합니다. 이는 런타임을 더 큰 애플리케이션에 내장할 때 유용합니다. 일반적인 설치와 달리, 이 경우 py``는 추출된 런타임을 인식하지 못하며 시작 메뉴나 다른 바로가기가 생성되지 않습니다. 런타임을 실행하려면 대상 디렉터리에 있는 메인 실행 파일(일반적으로 ``python.exe)을 직접 실행하십시오.

$> py install ... [-t=|--target=<PATH>] <TAG>

py exec 명령은 요청한 런타임이 없는 경우 이를 자동으로 설치합니다. 이는 automatic_install 설정(PYTHON_MANAGER_AUTOMATIC_INSTALL)에 의해 제어되며 기본적으로 활성화되어 있습니다. 사용 가능한 런타임이 전혀 없는 경우, 구성 설정이 허용한다면 모든 실행 명령에서 자동 설치가 수행됩니다. 이는 신규 사용자의 경험을 개선하기 위한 것이며, 일반적으로는 py exec 명령이나 명시적인 설치 명령을 사용하는 것을 권장합니다.

4.1.6. 오프라인 설치

Python을 오프라인으로 설치하려면 먼저 네트워크에 접속 가능한 기기에서 오프라인 인덱스를 생성해야 합니다.

$> py install --download=<PATH> ... <TAG>...

--download=<PATH> 옵션은 나열된 태그에 해당하는 패키지들을 다운로드하고, 해당 패키들과 나중에 설치하기 적합한 index.json 파일이 포함된 디렉터리를 생성합니다. 이 전체 디렉터리를 오프라인 기기로 이동하여 포함된 하나 이상의 런타임을 설치하는 데 사용할 수 있습니다.

$> py install --source="<PATH>\index.json" <TAG>...

Python 설치 관리자의 설치 프로그램을 다운로드하여 다른 기기로 옮긴 후 설치할 수 있습니다.

또는 오프라인 인덱스 디렉터리에 있는 ZIP 파일들을 다른 기기로 전송하여 압축을 풀 수도 있습니다. 이 경우 설치가 등록되지는 않으므로 추출된 디렉터리 내의 실행 파일을 직접 참조하여 실행해야 하지만, Python 설치 관리자를 설치할 수 없거나 편리하지 않은 상황에서는 선호되는 방법입니다.

이러한 방식을 통해 인터넷 연결이 없는 기기에서도 Python 런타임을 설치하고 관리할 수 있습니다.

4.1.7. 런타임 제거

$> py uninstall [-y|--yes] <TAG>...

py uninstall 명령을 사용하여 런타임을 제거할 수 있습니다. 하나 이상의 태그를 지정해야 하며, 범위(Range)는 지원되지 않습니다.

--yes 옵션은 제거 전 확인 프롬프트를 건너뜁니다.

태그를 개별적으로 전달하는 대신 --purge 옵션을 지정할 수 있습니다. 이 옵션은 시작 메뉴, 레지스트리 및 모든 다운로드 캐시를 정리하는 것을 포함하여 Python 설치 관리자가 관리하는 모든 런타임을 제거합니다. Python 설치 관리자로 설치되지 않은 런타임이나 수동으로 생성된 구성 파일은 영향을 받지 않습니다.

$> py uninstall [-y|--yes] --purge

Python 설치 관리자는 Windows의 “설치된 앱” 설정 페이지를 통해 제거할 수 있습니다. 이 경우 런타임은 제거되지 않으며 여전히 사용할 수 있지만, 전역 python 및 py 명령은 삭제됩니다. Python 설치 관리자를 다시 설치하면 이러한 런타임들을 다시 관리할 수 있습니다. 모든 Python 런타임을 완전히 정리하려면 Python 설치 관리제를 제거하기 전에 --purge 를 사용하여 실행하십시오.

4.1.8. 구성

Python 설치 관리자는 구성 파일, 환경 변수, 명령 줄 옵션 및 레지스트리 설정의 계층 구조를 통해 구성됩니다. 일반적으로 구성 파일은 다른 구성 파일의 위치를 포함한 모든 항목을 설정할 수 있는 능력이 있으며, 레지스트리 설정은 관리자 전용이며 구성 파일을 덮어씁니다. 명령 줄 옵션은 다른 모든 설정을 덮어쓰지만, 모든 옵션을 사용할 수 있는 것은 아닙니다.

이 섹션에서는 기본값을 설명하지만, 수정되었거나 재정의된 설치의 경우 설정이 다르게 해석될 수 있음에 유의하십시오.

관리자가 설정한 전역 구성 파일이 있을 수 있으며, 이 파일이 가장 먼저 읽힙니다. 사용자 구성 파일은 %AppData%Pythonpymanager.json`에 저장되며(참고: 이 경로는 ``Local``이 아닌 ``Roaming` 하위에 있습니다), 그 다음에 읽히며 이전 파일의 설정을 덮어씁니다. 추가 구성 파일은 PYTHON_MANAGER_CONFIG 환경 변수 또는 --config 명령 줄 옵션으로 지정할 수 있으며, 두 가지를 동시에 사용할 수는 없습니다. 이러한 위치는 나중에 나열된 관리자용 사용자 지정 옵션을 통해 수정될 수 있습니다.

다음 설정들은 일반적인 사용 환경에서 변경될 가능성이 높은 항목들입니다. 이후 섹션에서는 관리자용 사용자 지정을 위한 항목들을 나열합니다.

표준 구성 옵션

구성 키

환경 변수

설명

default_tag
PYTHON_MANAGER_DEFAULT

실행 또는 설치 시 선호되는 기본 버전입니다. 기본값은 CPython 팀에서 제공하는 가장 최신 비사전버전(non-prerelease)으로 해석됩니다.

default_platform

PYTHON_MANAGER_DEFAULT_PLATFORM

실행 또는 설치 시 선호되는 기본 플랫폼입니다. 이는 지정된 태그의 접미사로 처리됩니다. 예를 들어, default_platform 이 -64 일 때 py -V:3.14 를 실행하면 해당 태그가 존재하는 경우 3.14-64 설치를 우선 선택하며, 존재하지 않는 경우 3.14 를 사용합니다.

logs_dir

PYTHON_MANAGER_LOGS

로그 파일이 기록되는 위치입니다. 기본값은 %TEMP% 입니다.

automatic_install
PYTHON_MANAGER_AUTOMATIC_INSTALL

py exec 를 사용하여 실행할 때(또는 아직 런타임이 설치되지 않은 상태에서 py 를 사용할 때) 자동 설치를 허용하려면 True로 설정합니다. 다른 명령은 이 설정과 상관없이 자동으로 설치되지 않습니다. 기본값은 true입니다.

include_unmanaged

PYTHON_MANAGER_INCLUDE_UNMANAGED

Python 설치 관리자가 설치하지 않은 런타임을 목록에 표시하고 실행하는 것을 허용하려면 True, 제외하려면 False를 설정합니다. 기본값은 true입니다.

shebang_can_run_anything

PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING

.py 파일의 셔뱅이 Python 런타임이 아닌 다른 응용 프로그램을 실행하도록 허용하려면 True, 방지하려면 False를 설정합니다. 기본값은 true입니다.

shebang_templates

(없음)

셔뱅 줄 템플릿을 py -V:<tag> ` 또는 대체 문자열과 같은 대체 명령으로 매핑합니다. 자세한 내용은 셔뱅 줄 을 참조하십시오.

log_level

PYMANAGER_VERBOSE, PYMANAGER_DEBUG

기본 출력 수준을 설정합니다(0-50). 기본값은 20입니다. 값이 낮을수록 더 많은 출력이 생성됩니다. 환경 변수는 불리언 값이며, 시작 시 추가적인 출력을 생성할 수 있으나 이후 다른 구성에 의해 억제될 수 있습니다.

confirm

PYTHON_MANAGER_CONFIRM

특정 동작(예: 제거)을 수행하기 전에 확인을 요구하려면 True를, 확인을 생략하려면 False를 설정합니다. 기본값은 true입니다.

install.source

PYTHON_MANAGER_SOURCE_URL

새 설치를 가져올 인덱스 피드를 재정의합니다.

install.enable_entrypoints

(없음)

설치된 패키지에 대해 전역 명령(예: pip.exe)을 생성하려면 True를 설정합니다. 이러한 명령은 패키지 자체에 의해 정의됩니다. False로 설정하면 Python 인터프리터에 대해서만 전역 명령이 생성됩니다. 기본값은 true입니다. 이 설정을 변경한 후에는 py install --refresh 를 실행해야 합니다.

list.format

PYTHON_MANAGER_LIST_FORMAT

py list 명령에서 사용하는 기본 형식을 지정합니다. 기본값은 table 입니다.

install_dir

(없음)

런타임이 설치될 루트 디렉터리를 지정합니다. 이 설정을 변경하면 기존에 설치된 런타임을 새 위치로 이동하지 않는 한 사용할 수 없습니다.

global_dir

(없음)

전역 명령(예: python3.14.exe 및 pip.exe)이 저장되는 디렉터리를 지정합니다. 터미널에서 해당 명령을 사용하려면 이 디렉터리를 PATH 에 추가해야 합니다.

download_dir

(없음)

다운로드된 파일이 저장되는 디렉터리를 지정합니다. 이 디렉터리는 임시 캐시이며 정기적으로 정리할 수 있습니다.

점(.)이 포함된 이름은 JSON 객체 내에 중첩되어야 합니다. 예를 들어, list.format 은 {"list": {"format": "table"}} 로 지정해야 합니다.

4.1.9. 셔뱅 줄

스크립트 파일의 첫 번째 줄이 #!``로 시작하면 이를 "셔뱅(shebang)" 줄이라고 합니다. 리눅스와 기타 유닉스 계열 운영체제는 이러한 줄을 기본적으로 지원하며, 시스템에서 스크립트 실행 방법을 나타내는 데 흔히 사용됩니다. ``python 및 py 명령은 윈도우에서도 Python 스크립트에 대해 동일한 기능을 제공합니다.

Python 스크립트의 셔뱅 줄이 유닉스와 윈도우 간에 호환되도록 하기 위해, 어떤 인터프리터를 사용할지 지정하는 여러 ‘가상’ 명령을 지원합니다. 지원되는 가상 명령은 다음과 같습니다.

  • /usr/bin/env <ALIAS>

  • /usr/bin/env -S <ALIAS>

  • /usr/bin/<ALIAS>

  • /usr/local/bin/<ALIAS>

  • <ALIAS>

예를 들어, 스크립트의 첫 번째 줄이 다음과 같이 시작하면

#! /usr/bin/python

기본 파이썬이나 활성 가상 환경을 찾아서 사용합니다. 유닉스에서 작동하도록 작성된 많은 파이썬 스크립트에는 이미 이 줄이 있어서, 수정하지 않고도 이러한 스크립트를 런처에서 사용할 수 있습니다. 윈도우에서 유닉스에서 유용할 새 스크립트를 작성하면, /usr로 시작하는 셔뱅 줄 중 하나를 사용해야 합니다.

위 가상 명령 중 어느 것이든 <ALIAS> 부분을 설치된 런타임의 에일리어스로 대체할 수 있습니다. 즉, 전역 에일리어스 디렉터리(사용자가 PATH 환경 변수에 추가했을 수 있는 위치)에 생성된 모든 명령은 셔뱅에서 사용할 수 있으며, 이는 해당 명령이 현재 PATH`에 포함되어 있지 않더라도 가능합니다. 이를 통해 `/usr/bin/python3.12``와 같은 셔뱅을 사용하여 특정 런타임을 선택할 수 있습니다.

런타임이 설치되어 있지 않거나 자동 설치가 활성화된 경우, 필요한 경우 요청한 런타임이 설치됩니다. 구성 설정에 대한 정보는 구성 를 참조하십시오.

/usr/bin/env 형태의 셔뱅(shebang) 줄은 인식할 수 없는 명령에 대해 PATH 환경 변수를 검색합니다. 이는 동일한 검색을 수행하지만 알려진 파이썬 명령 실행을 선호하는 유닉스 env 프로그램의 동작과 일치합니다. 임의의 실행 파일을 검색할 때 경고가 표시될 수 있으며, 이 검색은 shebang_can_run_anything 구성 옵션에 의해 비활성화될 수 있습니다.

어떤 패턴과도 일치하지 않는 셔뱅 줄은 스크립트 파일이 포함된 디렉터리에 대한 절대 경로 또는 상대 경로인 Windows 실행 파일 경로로 취급됩니다. 이는 유닉스 스타일의 셸과 호환되지 않으므로 설치 프로그램에 의해 생성된 것과 같은 Windows 전용 스크립트를 위한 편의 기능입니다. 이러한 경로는 따옴표로 묶여 있을 수 있으며 여러 인수를 포함할 수 있으며, 이 경우 스크립트 경로와 추가 인수가 뒤에 추가됩니다. 이 기능은 shebang_can_run_anything 구성 옵션에 의해 비활성화될 수 있습니다.

Python 설치 관리자 버전 26.3부터 설정 파일에 사용자 정의 셔뱅 템플릿을 추가할 수 있습니다. shebang_templates 개체에 각 템플릿(일치할 문자열)과 해당 템플릿이 일치할 때 사용할 명령을 하나씩 추가하십시오. 대부분의 명령은 설치된 런타임 중 하나를 실행하기 위해 py -V:<tag>``(또는 ``pyw )여야 합니다. ` py -3.<version>` 형태도 허용되며, 기본값을 실행하는 일반 `` py``도 허용됩니다. 그 외 다른 인자는 지원되지 않습니다.

{
    "shebang_templates": {
        "/usr/bin/python": "py",
        "/usr/bin/my_custom_python": "py -V:MyCustomPython/3"
    }
}

대체 명령이 py 또는 pyw 가 아닌 경우, 해당 명령이 셔뱅에 다시 기록되고 일반적인 처리가 계속됩니다. 임의의 실행 파일 실행이 허용되는 경우, 전체 경로를 제공하여 파이썬에서 임의의 실행 파일로 리다이렉션할 수 있습니다. 템플릿은 셔뱅 줄 전체(앞뒤 공백 무시) 또는 셔뱅 줄의 첫 번째 공백까지 일치해야 합니다.

참고

Python 설치 관리자 내 셔뱅의 동작은 이전 py.exe 런처와 미세하게 다르며, 이전 구성 옵션은 더 이상 적용되지 않습니다. 이전 방식이나 구성을 반드시 사용해야 하는 경우 legacy launcher 를 설치하는 것을 권장합니다. 레거시 런처의 py 명령이 기본적으로 PyManager의 것을 대체하며, 이 경우 설치 및 제거를 위해 pymanager 명령을 사용해야 합니다.

4.1.10. 고급 설치

일부 오래된 관리용 배포 플랫폼과 같이 MSIX를 설치할 수 없는 상황의 경우, python.org 다운로드 페이지에서 제공하는 MSI 파일이 있습니다. 이 MSI는 사용자 인터페이스가 없으며, Program Files 내 기본 위치에 머신 단위로만 설치할 수 있습니다. 이 파일은 시스템 PATH 환경 변수에 해당 설치 경로를 포함하도록 수정을 시도하지만, 사용자의 구성에서 이를 확인해야 합니다.

참고

Windows Server 2019는 CPython이 지원하는 Windows 버전 중 유일하게 MSIX를 지원하지 않는 버전입니다. Windows Server 2019에서는 MSI를 사용해야 합니다.

MSI 패키지에는 어떤 런타임도 포함되어 있지 않으므로, 오프라인 설치 인덱스를 생성하지 않고는 오프라인 환경에 설치하는 데 적합하지 않다는 점에 유의하십시오. 이러한 시나리오를 처리하는 방법에 대한 정보는 오프라인 설치 및 관리자 설정 를 참조하십시오.

Runtimes installed by the MSI are shared with those installed by the MSIX, and are all per-user only. The Python install manager does not support installing runtimes per-machine. To emulate a per-machine install, you can use py install --target=<shared location> as administrator and add your own system-wide modifications to PATH, the registry, or the Start menu.

MSIX가 설치되었으나 명령을 PATH 환경 변수에서 찾을 수 없는 경우, 설치 경로가 python.org를 통해 설치되었는지 아니면 Windows Store를 통해 설치되었는지에 따라 %LocalAppData%MicrosoftWindowsAppsPythonSoftwareFoundation.PythonManager_3847v3x7pw1km 또는 %LocalAppData%MicrosoftWindowsAppsPythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0 아래에 위치할 수 있습니다. Program Files에서 실행 파일을 직접 실행하는 것은 권장되지 않습니다.

Python 설치 관리자를 프로그램 방식으로 설치하려면 모든 지원되는 Windows 버전에 포함된 WinGet을 사용하는 것이 가장 쉽습니다:

$> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity

# 선택적으로 구성 확인기를 실행하고 모든 변경 사항을 수락합니다
$> py install --configure -y

To download the Python install manager and install on another machine, the following WinGet command will download the required files from the Store to your Downloads directory (add -d <location> to customize the output location). This also generates a YAML file that appears to be unnecessary, as the downloaded MSIX can be installed by launching or using the commands below.

$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements

PowerShell만 사용하여 MSIX를 프로그램 방식으로 설치하거나 제거하려면 Add-AppxPackage 및 Remove-AppxPackage PowerShell cmdlet을 권장합니다:

$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
...
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage

최신 버전은 Add-AppxPackage 명령에 AppInstaller 파일을 전달하여 Windows에서 다운로드하고 설치할 수 있습니다. 이 방법은 python.org의 MSIX를 사용하여 설치하며, Store를 통해(대화형 또는 WinGet 사용) 설치가 불가능한 경우에만 권장됩니다.

$> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller

머신 내 모든 사용자를 위해 MSIX 패키지를 제공하기 위해 다른 도구 및 API를 사용할 수도 있지만, Python은 이를 지원되는 시나리오로 간주하지 않습니다. PowerShell의 Add-AppxProvisionedPackage cmdlet, 네이티브 Windows PackageManager 클래스 또는 배포 도구의 관련 설명서와 지원 정보를 확인해 보시기 바랍니다.

설치 방법과 관계없이, 로그인된 사용자가 아니면 해당 설치를 실행할 수 있는 방법이 없으므로 사용자는 여전히 파이썬 자체를 직접 설치해야 합니다. MSIX를 사용할 경우, 네트워크 연결 없이도 모든 사용자가 최신 버전의 파이썬을 설치할 수 있게 됩니다.

Store에서 다운로드하는 MSIX와 Python 웹사이트에서 다운로드하는 MSIX는 미세하게 다르며 동시에 설치할 수 없다는 점에 유의하십시오. 가능한 경우, 충돌하는 설치가 설정될 위험을 줄이기 위해 위에서 설명한 WinGet 명령을 사용하여 Store에서 패키지를 다운로드하는 것을 권장합니다. 이러한 방식으로 Store 패키지를 사용하는 데 있어 Python 설치 관리자의 라이선스 제한은 없습니다.

4.1.11. 관리자 설정

관리자가 Python 설치 관리자의 구성을 재정의하는 데 유용할 수 있는 여러 옵션이 있습니다. 이러한 옵션은 로컬 캐싱 제공, 특정 바로가기 유형 비활성화, 내장 콘텐츠 재정의 등에 사용될 수 있습니다. 아래에 나열된 옵션뿐만 아니라 위의 모든 구성 옵션을 설정할 수 있습니다.

구성 옵션은 HKEY_LOCAL_MACHINESoftwarePoliciesPythonPyManager 아래의 값을 설정하여 레지스트리에서 재정의할 수 있으며, 값 이름은 구성 키와 일치하고 값 유형은 REG_SZ 입니다. 이 키 자체를 사용자 지정하려면 Python 설치 관리제와 함께 제공되는 핵심 구성 파일을 수정해야 합니다. 그러나 권장되는 방법은 레지스트리 값을 사용하여 모든 재정의 세트를 포함하는 JSON 파일로 base_config 를 설정하는 것입니다. 레지스트리 키 재정의는 다른 모든 구성 설정을 대체하며, base_config 는 사용자가 필요한 설정을 추가로 수정할 수 있게 해줍니다.

대부분의 환경 변수 관련 설정은 기본값이 해당 변수를 지정하기 때문에 해당 변수를 지원한다는 점에 유의하십시오. 이 값을 재정의하면, 다른 값으로 재정의하지 않는 한 환경 변수가 더 이상 작동하지 않습니다. 예를 들어, confirm 의 기본값은 문자 그대로 %PYTHON_MANAGER_CONFIRM% 이며, 이는 로드 시점에 해당 변수를 해석합니다. 이 값을 yes 로 재정의하면 환경 변수가 더 이상 사용되지 않습니다. 이 값을 %CONFIRM% 으로 재정의하면 대신 해당 환경 변수가 사용됩니다.

경로인 구성 설정은 해당 설정을 명시한 구성 파일이 포함된 디렉터리를 기준으로 상대 경로로 해석됩니다.

관리자용 구성 옵션

구성 키

설명

base_config

읽어올 가장 우선순위가 높은 구성 파일입니다. 내장 구성 파일과 레지스트리만 이 설정을 수정할 수 있습니다.

user_config

두 번째로 읽을 구성 파일입니다.

additional_config

세 번째로 읽을 구성 파일입니다.

registry_override_key

재정의 여부를 확인할 레지스트리 위치입니다. 내장 구성 파일만 이 설정을 수정할 수 있습니다.

bundled_dir

로컬에 캐시된 파일이 포함된 읽기 전용 디렉터리입니다.

install.fallback_source

기본 인덱스에 접근할 수 없을 때 참조할 인덱스의 경로 또는 URL입니다.

install.enable_shortcut_kinds

허용할 바로가기 종류의 쉼표로 구분된 목록(예: "pep514,start"). 활성화된 바로가기는 disable_shortcut_kinds 에 의해 여전히 비활성화될 수 있습니다.

install.disable_shortcut_kinds

제외할 바로가기 종류의 쉼표로 구분된 목록(예: "pep514,start"). 비활성화된 바로가기는 enable_shortcut_kinds 에 의해 재활성화되지 않습니다.

install.hard_link_entrypoints

디스크 공간을 절약하기 위해 전역 바로가기에 하드 링크를 사용하려면 True로 설정하십시오. False인 경우, 각 바로가기 실행 파일이 복사됩니다. 이 설정을 변경한 후에는 기존 명령을 업데이트하기 위해 py install --refresh --force 를 실행해야 합니다. 기본값은 true입니다. 문제 해결이나 파일 링크에 문제가 있는 시스템에서는 이를 비활성화해야 할 수도 있습니다.

pep514_root

PEP 514 항목을 읽고 쓰는 레지스트리 위치입니다. 기본값은 HKEY_CURRENT_USERSoftwarePython 입니다.

start_folder

바로가기를 기록할 시작 메뉴 폴더입니다. 기본값은 Python 이며, 이 경로는 사용자의 프로그램(Programs) 폴더를 기준으로 한 상대 경로입니다.

virtual_env

활성화된 가상 환경의 경로입니다. 기본값은 %VIRTUAL_ENV% 이지만, venv 감지를 비활성화하려면 빈 값으로 설정할 수 있습니다.

shebang_can_run_anything_silently

셔뱅이 파이썬 런타임이 아닌 다른 애플리케이션을 실행할 때 표시되는 경고를 숨기려면 True로 설정하십시오.

source_settings

원본 URL에서 해당 인덱스 전용 설정을 가져오는 매핑입니다. 여러 구성 파일에 이 섹션이 포함된 경우, URL 설정은 추가되거나 덮어씌워지지만 개별 설정은 병합되지 않습니다. 이 설정은 현재 index signatures 만을 위한 것입니다.

4.1.12. free-threaded 바이너리 설치

Added in version 3.13.

t 접미사가 붙은 태그를 설치하면 free-threaded 빌드의 사전 제작 배포판을 사용할 수 있습니다.

$> py install 3.14t
$> py install 3.14t-arm64
$> py install 3.14t-32

이것은 정상적으로 설치되고 등록됩니다. 다른 런타임이 설치되어 있지 않다면 python 명령은 이 런타임을 실행합니다. 그렇지 않은 경우, py -V:3.14t ... 또는 PATH 환경 변수에 전역 별칭(alias) 디렉터리를 추가했다면 python3.14t.exe 명령을 사용해야 합니다.

4.1.13. 인덱스 서명

Added in version 26.2.

인덱스 파일은 변조 여부를 확인하기 위해 서명될 수 있습니다. 서명은 인덱스와 동일한 URL에 .cat 이 추가된 이름의 카탈로그 파일입니다. 카탈로그 파일은 일치하는 인덱스 파일의 해시를 포함해야 하며, 유효한 Authenticode 서명으로 서명되어야 합니다. 이를 통해 표준 도구(Windows 환경)가 서명을 생성할 수 있으며, 클라이언트 운영체제가 해당 인증 기관(root CA)을 신뢰하는 한 어떤 인증서든 사용할 수 있습니다.

인덱스 서명은 로컬 구성의 source_settings 섹션에 인덱스 URL이 포함되고 requires_signature 가 true로 설정되어 있거나, 인덱스 JSON에 requires_signature 가 true로 설정된 경우에만 다운로드되고 확인됩니다. 로컬 구성에 해당 설정이 존재하는 경우, false라 하더라도 인덱스의 설정을 무시합니다.

유효한 서명이 필요할 뿐만 아니라, required_root_subject 및 required_publisher_subject 설정을 통해 인증서의 Subject 필드에 따라 허용되는 서명을 추가로 제한할 수 있습니다. 구성에 지정된 모든 속성은 인증서의 속성과 일치해야 합니다(인증서 내 추가 속성은 무시됩니다). 일반적인 속성으로는 공통 이름인 CN=, 조직 단위인 O=, 발행자 국가인 C= 등이 있습니다.

마지막으로, required_publisher_eku 설정은 발행자 인증서에 특정 강화된 키 사용(EKU)이 할당되어 있는지 요구할 수 있습니다. 예를 들어, EKU 1.3.6.1.5.5.7.3.3 은 이 인증서가 서버 또는 클라이언트 인증이 아닌 코드 서명용으로 의도되었음을 나타냅니다. 특정 루트 CA와 결합하면 정당한 서명을 확인하는 또 다른 메커니즘을 제공합니다.

이는 구성 파일의 source_settings 섹션 예시입니다. 이 경우, 피드의 발행자는 Microsoft Identity Verification root와 해당 루트에서 할당된 EKU의 조합으로 고유하게 식별됩니다. 이 경우의 서명은 https://www.python.org/ftp/python/index-windows.json.cat 에서 찾을 수 있습니다.

{
  "source_settings": {
    "https://www.python.org/ftp/python/index-windows.json": {
      "requires_signature": true,
      "required_root_subject": "CN=Microsoft Identity Verification Root Certificate Authority 2020",
      "required_publisher_subject": "CN=Python Software Foundation",
      "required_publisher_eku": "1.3.6.1.4.1.311.97.608394634.79987812.305991749.578777327"
    }
  }
}

동일한 설정을 index.json 파일에 대신 지정할 수도 있습니다. 이 경우 루트와 EKU가 생략되므로, 서명은 유효해야 하며 발행자의 인증서에 특정 공통 이름(common name)이 있어야 하지만 다른 확인 절차는 사용되지 않습니다.

{
  "requires_signature": true,
  "required_publisher_subject": "CN=Python Software Foundation",
  "versions": [
    // ...
  ]
}

피드 내부의 설정을 사용할 경우 사용자에게 알림이 표시되고 해당 설정은 로그 파일이나 상세 출력(verbose output)에 표시됩니다. 자주 사용하는 피드의 경우, 피드에 대한 무단 수정으로 인해 검증이 비활성화되는 것을 방지하기 위해 해당 설정을 로컬 구성 파일로 복사하는 것이 좋습니다.

피드 내에서 또는 구성 파일을 통해 서명 파일의 위치를 재정의할 수 없습니다. 관리자는 필수 구성 파일에 자신만의 source_settings 를 제공할 수 있습니다(참고: 관리자 설정).

서명 검증에 실패하면 알림이 표시되고 계속 여부를 묻습니다. 대화형 확인이 허용되지 않는 경우(예를 들어 --yes 가 지정된 경우), 항상 중단됩니다. 이러한 상황에서 잘못된 구성을 가진 피드를 사용하려면 해당 피드에 대한 서명 확인을 비활성화하는 구성 파일을 제공해야 합니다.

"source_settings": {
  "https://www.example.com/feed-with-invalid-signature.json": {
    "requires_signature": false
  }
}

4.1.14. 문제 해결

Python 설치 매니저가 제대로 작동하지 않는 것 같다면, 다음 테스트와 해결 방법을 시도해 보십시오. 문제가 해결되지 않으면 관련 로그 파일(기본적으로 %TEMP% 디렉토리에 기록됨)을 포함하여 버그 추적기 에 문제를 보고해 주시기 바랍니다.

문제 해결

증상

시도해 볼 사항

터미널에 python 을 입력했을 때 “명령어를 찾을 수 없음(command not found)” 오류가 발생하거나 스토어 앱이 열립니다.

Python 설치 매니저를 설치하셨나요?

시작을 클릭하고 “앱 실행 별칭 관리”를 열어 “Python (기본값)”의 별칭이 활성화되어 있는지 확인하십시오. 이미 활성화되어 있다면, 명령을 새로고침하기 위해 비활성화 후 다시 활성화해 보십시오. “Python (기본값 창 모드)” 및 “Python 설치 매니저” 명령도 새로 고침이 필요할 수 있습니다.

py 및 pymanager 명령어가 작동하는지 확인하십시오.

사용자의 PATH 변수에 %UserProfile%\AppData\Local\Microsoft\WindowsApps 항목이 포함되어 있는지 확인하십시오. 운영 체제는 다른 사용자 경로 다음에 이 항목을 기본적으로 한 번 포함합니다. 제거될 경우 바로 가기를 찾을 수 없습니다.

터미널에 py 를 입력했을 때 “명령어를 찾을 수 없음(command not found)” 오류가 발생합니다.

Python 설치 매니저를 설치하셨나요?

시작을 클릭하고 “앱 실행 별칭 관리”를 열어 “Python (기본값)”의 별칭이 활성화되어 있는지 확인하십시오. 이미 활성화되어 있다면, 명령을 새로고침하기 위해 비활성화 후 다시 활성화해 보십시오. “Python (기본값 창 모드)” 및 “Python 설치 매니저” 명령도 새로 고침이 필요할 수 있습니다.

사용자의 PATH 변수에 %UserProfile%\AppData\Local\Microsoft\WindowsApps 항목이 포함되어 있는지 확인하십시오. 운영 체제는 다른 사용자 경로 다음에 이 항목을 기본적으로 한 번 포함합니다. 제거될 경우 바로 가기를 찾을 수 없습니다.

터미널에 명령을 입력했을 때 py 에서 “파일을 열 수 없음(can’t open file)” 오류가 발생합니다.

이는 일반적으로 레거시 런처가 설치되어 있으며 그것이 Python 설치 매니저보다 우선순위를 갖는다는 것을 의미합니다. 제거하려면 시작을 클릭하고 “설치된 앱”을 열어 “Python launcher”를 검색한 후 제거하십시오.

python 이 py 와 동일한 런타임을 실행하지 않습니다.

시작을 클릭하고 “설치된 앱”을 열어 기존의 Python 런타임을 찾아 제거하거나, 수정하여 PATH 옵션을 비활성화하십시오.

시작을 클릭하고 “앱 실행 별칭 관리”를 열어 python.exe 별칭이 “Python (기본값)”으로 설정되어 있는지 확인하십시오.

python 및 py 가 예상한 런타임을 실행하지 않습니다.

PYTHON_MANAGER_DEFAULT 환경 변수 또는 default_tag 구성을 확인하십시오. py list 명령은 이러한 설정에 기반한 기본값을 표시합니다.

Python 설치 매니저에 의해 관리되는 설치 항목이 관리되지 않는 항목보다 우선 선택됩니다. 원하는 런타임을 설치하려면 py install 을 사용하거나 기본 태그를 구성하십시오.

Python 설치 매니저에 의해 관리되지 않는 프리릴리스 및 실험적 설치 항목이 안정적인 버전보다 우선 선택될 수 있습니다. 기본 태그를 구성하거나, 프리릴리스 런타임을 제거하고 py install 을 사용하여 재설치하십시오.

pythonw 또는 pyw 가 python 또는 py 와 동일한 런타임을 실행하지 않습니다.

시작을 클릭하고 “앱 실행 별칭 관리”를 열어 pythonw.exe 및 pyw.exe 별칭이 다른 것들과 일치하는지 확인하십시오.

터미널에 pip 를 입력했을 때 “명령어를 찾을 수 없음(command not found)” 오류가 발생합니다.

가상 환경을 활성화하셨습니까? 터미널에서 .venv\Scripts\activate 스크립트를 실행하여 활성화하십시오.

패키지는 존재하지만 생성된 실행 파일이 없을 수 있습니다. 대신 python -m pip 명령을 사용하는 것을 권장합니다. py install --refresh 를 실행하고 글로벌 바로 가기 디렉터리가 PATH 에 포함되어 있는지 확인하면(포함되지 않은 경우 명령 결과에 표시됨), pip (및 기타 설치된 패키지)과 같은 명령어를 사용할 수 있게 됩니다.

pip 으로 패키지를 설치했지만 해당 명령을 찾을 수 없습니다.

가상 환경을 활성화하셨습니까? 터미널에서 .venv\Scripts\activate 스크립트를 실행하여 활성화하십시오.

새로 설치된 패키지는 Python 설치 매니저에 의해 자동으로 생성되는 글로벌 바로 가기를 가지지 않습니다. 마찬가지로, 제거된 패키지의 바로 가치도 삭제되지 않습니다. 새로 설치된 패키지를 위한 글로벌 바로 가기를 업데이트하려면 py install --refresh 를 실행하십시오.

터미널에 script-name.py 를 입력하면 새 창에서 열립니다.

이는 운영 체제의 알려진 제한 사항입니다. 스크립트 이름 앞에 py 를 명시하거나, 스크립트와 동일한 이름을 가진 @py "%~dpn0.py" %* 포함 배치 파일을 생성하거나, legacy launcher 를 설치하고 이를 스크립트 연결 프로그램으로 선택하십시오.

스크립트로 파일을 드래그 앤 드롭하는 기능이 작동하지 않습니다.

이는 운영 체제의 알려진 제한 사항입니다. 이 기능은 레거시 런처 또는 MSI를 통해 설치한 경우의 Python 설치 매니저에서 지원됩니다.

Python 설치 매니저를 여러 번 설치했습니다.

Store 또는 WinGet, Python 웹사이트의 MSIX, 그리고 MSI를 통해 한꺼번에 설치할 수 있습니다. 이들은 모두 호환되며 구성 및 런타임을 공유합니다.

일반적인 설치된 앱(프로그램 추가/제거) 설정 페이지 외에 설치 매니저를 제거하는 방법은 앞선 고급 설치 섹션을 참조하십시오.

기존의 py.ini 설정이 더 이상 작동하지 않습니다.

새로운 Python 설치 매니저는 더 이상 이 구성 파일이나 해당 설정을 지원하지 않으므로 무시됩니다. 구성 설정에 대한 자세한 정보는 구성 를 참조하십시오.

4.2. 내장 가능한 패키지

Added in version 3.5.

내장된 배포는 최소 파이썬 환경을 포함하는 ZIP 파일입니다. 최종 사용자가 직접 액세스하기보다는, 다른 응용 프로그램의 일부로 작동하기 위한 것입니다.

임베디드 배포판을 설치하려면 --target 옵션과 함께 py install 을 사용하는 것을 권장합니다.

$> py install 3.14-embed --target=<디렉터리>

추출된 임베디드 배포판은 환경 변수, 시스템 레지스트리 설정 및 설치된 패키지를 포함하여 사용자 시스템으로부터 (거의) 완전히 격리됩니다. 표준 라이브러리는 ZIP 내에 사전 컴파일되고 최적화된 .pyc 파일로 포함되며, python3.dll, python313.dll, python.exe 및 pythonw.exe 가 모두 제공됩니다. Tcl/tk(Idle와 같은 모든 종속성 포함), pip 및 Python 문서는 포함되지 않습니다.

기본 ._pth 파일이 포함되어 있으며, 이는 기본 검색 경로를 더욱 제한합니다(아래 모듈 찾기 에서 설명). 이 파일은 임베더가 필요에 따라 수정할 수 있도록 제공됩니다.

제삼자 패키지는 내장된 배포와 함께 응용 프로그램 설치 프로그램이 설치해야 합니다. 일반 파이썬 설치처럼 종속성을 관리하기 위해 pip를 사용하는 것은 이 배포에서 지원되지 않지만, 주의를 기울이면 자동 업데이트를 위해 pip를 포함하고 사용할 수 있습니다. 일반적으로, 제삼자 패키지는 개발자가 사용자에게 업데이트를 제공하기 전에 최신 버전과의 호환성을 보장할 수 있도록 응용 프로그램의 일부로 처리되어야 합니다 (“벤더링(vendoring)”).

이 배포에 권장되는 두 가지 사용 사례가 아래에 설명되어 있습니다.

4.2.1. Python 애플리케이션

파이썬으로 작성된 응용 프로그램이 반드시 사용자가 그 사실을 인식하도록 할 필요는 없습니다. 이 경우 내장된 배포를 사용하여 설치 패키지에 파이썬의 내부 버전을 포함할 수 있습니다. 얼마나 투명해야 하는지(또는 반대로, 얼마나 전문적으로 보여야 하는지)에 따라, 두 가지 옵션이 있습니다.

특수 실행 파일을 런처로 사용하려면 약간의 코딩이 필요하지만, 사용자에게 가장 투명한 경험을 제공합니다. 사용자 정의된 런처를 사용하면, 프로그램이 파이썬에서 실행되고 있다는 명백한 표시가 없습니다: 아이콘을 사용자 정의하고, 회사와 버전 정보를 지정할 수 있으며 파일 연결이 제대로 작동합니다. 대부분의 경우, 사용자 정의 런처는 하드 코딩된 명령 줄을 사용하여 Py_Main을 호출할 수 있어야 합니다.

더 간단한 방법은 필요한 명령 줄 인자를 사용하여 python.exe나 pythonw.exe를 직접 호출하는 배치 파일이나 생성된 바로 가기를 제공하는 것입니다. 이 경우, 응용 프로그램은 실제 이름이 아닌 파이썬으로 표시되며, 사용자는 실행 중인 다른 파이썬 프로세스나 파일 연결과 구별하는 데 어려움을 겪을 수 있습니다.

후자의 접근 방식에서는, 패키지를 파이썬 실행 파일과 함께 디렉터리로 설치하여 경로에서 사용할 수 있도록 해야 합니다. 특수 런처를 사용하면, 응용 프로그램을 시작하기 전에 검색 경로를 지정할 수 있어서 패키지를 다른 위치에 배치할 수 있습니다.

4.2.2. 파이썬 내장하기

네이티브 코드로 작성된 응용 프로그램에는 종종 어떤 형태의 스크립팅 언어가 필요하며, 내장된 파이썬 배포를 이러한 목적으로 사용할 수 있습니다. 일반적으로, 대부분의 응용 프로그램은 네이티브 코드로 되어 있으며, 일부가 python.exe를 호출하거나 python3.dll을 직접 사용합니다. 두 경우 모두, 내장된 배포를 응용 프로그램 설치의 하위 디렉터리로 추출하면 로드할 수 있는 파이썬 인터프리터를 제공하기에 충분합니다.

응용 프로그램 사용과 마찬가지로, 인터프리터를 초기화하기 전에 검색 경로를 지정할 기회가 있어서 패키지를 임의의 위치에 설치할 수 있습니다. 그 외에는, 내장된 배포와 일반 설치를 사용하는 것 간에 근본적인 차이점은 없습니다.

4.3. nuget.org 패키지

Added in version 3.5.2.

nuget.org 패키지는 시스템 전체에 파이썬이 설치되지 않은 지속적인 통합과 빌드 시스템에 사용하기 위한 축소된 크기의 파이썬 환경입니다. 너겟은 “.NET 용 패키지 관리자”이지만, 빌드 타임 도구가 포함된 패키지에서도 완벽하게 작동합니다.

너겟 사용에 대한 최신 정보를 보려면 nuget.org를 방문하십시오. 다음은 파이썬 개발자에게 충분한 요약입니다.

nuget.exe 명령 줄 도구는 예를 들어 curl이나 PowerShell을 사용하여 https://dist.nuget.org/win-x86-commandline/latest/nuget.exe 에서 직접 다운로드할 수 있습니다. 이 도구를 사용하면 다음과 같이 64비트 또는 32비트 머신용 파이썬 최신 버전이 설치됩니다:

nuget.exe install python -ExcludeVersion -OutputDirectory .
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .

특정 버전을 선택하려면, -Version 3.x.y를 추가하십시오. 출력 디렉터리는 .에서 변경될 수 있으며, 패키지는 하위 디렉터리에 설치됩니다. 기본적으로, 하위 디렉터리의 이름은 패키지와 같으며, -ExcludeVersion 옵션이 없으면 이 이름에 설치된 특정 버전이 포함됩니다. 하위 디렉터리에는 파이썬 설치가 포함된 tools 디렉터리가 있습니다:

# -ExcludeVersion 없이
> .\python.3.5.2\tools\python.exe -V
Python 3.5.2

# -ExcludeVersion 포함
> .\python\tools\python.exe -V
Python 3.5.2

일반적으로, 너겟 패키지는 업그레이드할 수 없으며, 최신 버전을 나란히 설치하고 전체 경로를 사용하여 참조해야 합니다. 또는, 패키지 디렉터리를 수동으로 삭제하고 다시 설치하십시오. 많은 CI 시스템은 빌드 간에 파일을 보존하지 않으면 이 작업을 자동으로 수행합니다.

tools 디렉터리와 함께 build\native 디렉터리가 있습니다. 여기에는 파이썬 설치를 참조하기 위해 C++ 프로젝트에서 사용할 수 있는 MSBuild 속성 파일 python.props가 포함되어 있습니다. 설정을 포함하면 빌드에서 자동으로 헤더와 임포트 라이브러리를 사용합니다.

nuget.org의 패키지 정보 페이지는 64비트 버전의 경우 www.nuget.org/packages/python, 32비트 버전의 경우 www.nuget.org/packages/pythonx86 그리고 ARM64 버전의 경우 www.nuget.org/packages/pythonarm64입니다.

4.3.1. 자유 스레드 패키지

Added in version 3.13.

프리 스레딩(free-threaded) 바이너리를 포함하는 패키지는 64비트 버전의 경우 python-freethreaded , 32비트 버전의 경우 pythonx86-freethreaded , ARM64 버전의 경우 pythonarm64-freethreaded 로 명명됩니다. 이 패키지들은 모두 프리 스레딩으로 실행되는 python3.13t.exe``와 ``python.exe 진입점을 모두 포함합니다.

4.4. 대체 번들

표준 CPython 배포 외에도, 추가 기능을 포함하는 수정된 패키지가 있습니다. 다음은 많이 사용되는 버전과 주요 기능 목록입니다:

ActivePython

다중 플랫폼 호환성, 설명서, PyWin32가 있는 설치 프로그램

Anaconda

인기 있는 과학 모듈(가령 numpy, scipy 및 pandas)과 conda 패키지 관리자.

Enthought Deployment Manager

“차세대 파이썬 환경 및 패키지 관리자”.

이전에는 Enthought에서 Canopy를 제공했으나, 2016년에 서비스가 종료되었습니다.

WinPython

사전 빌드된 과학 패키지와 패키지 빌드를 위한 도구가 포함된 윈도우 전용 배포.

이러한 패키지들은 최신 버전의 파이썬이나 기타 라이브러리를 포함하지 않을 수 있으며, 핵심 파이썬 팀에서 유지 관리하거나 지원하지 않음에 유의하십시오.

4.5. 지원되는 Windows 버전

As specified in PEP 11, a Python release only supports a Windows platform while Microsoft considers the platform under extended support. This means that Python 3.16 supports Windows 10 and newer. If you require Windows 7 support, please install Python 3.8. If you require Windows 8.1 support, please install Python 3.12.

4.6. MAX_PATH 제한 제거

윈도우는 역사적으로 경로 길이를 260자로 제한했습니다. 이는 이보다 긴 경로는 결정(resolve)되지 않고 에러가 발생함을 의미합니다.

최신 버전의 Windows에서 이 제한은 32,000자 이상으로 확장될 수 있습니다. 관리자가 “Enable Win32 long paths” 그룹 정책을 활성화하거나, 레지스트리 키 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem 에 LongPathsEnabled 를 1 로 설정해야 합니다.

이는 open() 함수, os 모듈 및 대부분의 다른 경로 기능이 260자보다 긴 경로를 받아들이고 반환할 수 있도록 합니다.

위 옵션을 변경하고 재부팅한 후에는 추가 구성이 필요하지 않습니다.

4.7. UTF-8 모드

Added in version 3.7.

버전 3.15에서 변경: 이제 Python UTF-8 모드가 기본으로 활성화됩니다 (PEP 686).

윈도우는 여전히 시스템 인코딩에 레거시 인코딩을 사용합니다 (ANSI 코드 페이지). 파이썬은 이를 텍스트 파일의 기본 인코딩에 이를 사용합니다 (예를 들어 locale.getencoding()).

UTF-8은 인터넷과 WSL(Windows Subsystem for Linux)을 포함한 대부분의 유닉스 시스템에서 널리 사용되기 때문에 문제가 발생할 수 있습니다.

기본으로 활성화되는 파이썬 UTF-8 모드 는 기본 텍스트 인코딩을 UTF-8로 변경하여 도움이 될 수 있습니다. UTF-8 모드 가 활성화된 경우에도 “mbcs” 코덱을 통해 시스템 인코딩(ANSI 코드 페이지)을 계속 사용할 수 있습니다.

-X utf8=0 명령 줄 옵션이나 PYTHONUTF8=0 환경 변수를 통해 파이썬 UTF-8 모드 를 비활성화할 수 있습니다. UTF-8 모드 비활성화에 대해서는 PYTHONUTF8 을, 환경 변수 수정 방법은 Python Install Manager 를 참조하십시오.

힌트

기본 환경 변수에 PYTHONUTF8={0,1}``을 추가하면 시스템의 모든 Python 3.7+ 애플리케이션에 영향을 미칩니다. 레거시 시스템 인코딩에 의존하는 Python 3.7+ 애플리케이션이 있는 경우, 환경 변수를 임시로 설정하거나 ``-X utf8 명령 줄 옵션을 사용하는 것을 권장합니다.

참고

UTF-8 모드가 비활성화된 경우에도, 파이썬은 윈도우에서 기본적으로 다음을 위해 UTF-8을 사용합니다:

4.8. 모듈 찾기

이 노트들은 상세한 Windows 관련 내용을 포함하여 sys.path 모듈 검색 경로의 초기화 의 설명을 보완합니다.

._pth 파일이 없을 때, 윈도우에서 sys.path를 채우는 방법은 다음과 같습니다:

  • 시작에 현재 디렉터리에 해당하는 빈 항목이 추가됩니다.

  • 환경 변수에 설명된 대로, 환경 변수 PYTHONPATH가 존재하면, 해당 항목이 다음에 추가됩니다. 윈도우에서, 이 변수의 경로는 드라이브 식별자(C:\ 등)에 사용되는 콜론과 구별하기 위해 세미콜론으로 구분되어야 합니다.

  • 추가 “응용 프로그램 경로”는 HKEY_CURRENT_USER와 HKEY_LOCAL_MACHINE 하이브 모두의 아래에 \SOFTWARE\Python\PythonCore{version}\PythonPath의 하위 키로 레지스트리에 추가될 수 있습니다. 세미콜론으로 구분된 경로 문자열을 기본값으로 사용하는 하위 키는 각 경로가 sys.path에 추가되도록 합니다. (알려진 모든 설치 프로그램은 HKLM 만 사용하므로, HKCU는 일반적으로 비어 있음에 유의하십시오.)

  • 환경 변수 PYTHONHOME이 설정되면, “파이썬 홈”으로 간주합니다. 그렇지 않으면, 메인 파이썬 실행 파일의 경로를 사용하여 “랜드마크 파일”(Lib\os.py나 pythonXY.zip)을 찾아 “파이썬 홈”을 추론합니다. 파이썬 홈이 발견되면, sys.path에 추가되는 관련 하위 디렉터리(Lib, plat-win 등)는 해당 폴더를 기반으로 합니다. 그렇지 않으면, 핵심 파이썬 경로가 레지스트리에 저장된 PythonPath에서 구성됩니다.

  • 파이썬 홈을 찾을 수 없고, 환경에 PYTHONPATH가 지정되어 있지 않고, 레지스트리 항목을 찾을 수 없으면, 상대 항목의 기본 경로(예를 들어 .\Lib;.\plat-win 등)가 사용됩니다.

pyvenv.cfg 파일이 메인 실행 파일과 함께 또는 실행 파일보다 한 수준 위의 디렉터리에서 발견되면, 다음 변형이 적용됩니다:

  • home이 절대 경로이고 PYTHONHOME이 설정되지 않으면, 홈 위치를 추론할 때 메인 실행 파일에 대한 경로 대신 이 경로가 사용됩니다.

이 모든 것의 최종 결과는 다음과 같습니다:

  • python.exe 또는 기본 파이썬 디렉터리 (설치된 버전 또는 PCbuild 디렉터리에서 직접)에서 다른 .exe를 실행할 때 핵심 경로가 추론되고 레지스트리의 핵심 경로가 무시됩니다. 레지스트리의 다른 “응용 프로그램 경로”는 항상 읽습니다.

  • 파이썬이 다른 .exe(다른 디렉터리, COM을 통한 내장, 등)에서 호스팅 될 때, “파이썬 홈”이 추론되지 않아서, 레지스트리의 핵심 경로가 사용됩니다. 레지스트리의 다른 “응용 프로그램 경로”는 항상 읽힙니다.

  • 파이썬이 홈을 찾을 수 없고 레지스트리 값이 없으면 (고정된(frozen) .exe, 아주 이상한 설치 설정), 일부 기본 (하지만 상대) 경로를 얻게 됩니다.

파이썬을 응용 프로그램이나 배포에 번들로 포함하려는 사용자를 위해, 다음 조언은 다른 설치와의 충돌을 방지합니다:

  • 포함할 디렉터리가 포함된 실행 파일과 함께 ._pth 파일을 포함합니다. 이것은 레지스트리와 환경 변수에 나열된 경로를 무시하고, import site가 나열되지 않는 한 site도 무시합니다.

  • 여러분 자신의 실행 파일에서 python3.dll이나 python37.dll을 로드하면, Py_InitializeFromConfig() 전에 PyConfig.module_search_paths 를 명시적으로 설정하십시오.

  • 응용 프로그램에서 python.exe를 시작하기 전에 PYTHONPATH를 지우거나 덮어쓰고 PYTHONHOME를 설정하십시오.

  • 이전 제안을 사용할 수 없으면 (예를 들어, 사용자가 python.exe를 직접 실행할 수 있는 배포판이면), 랜드마크 파일(Lib\os.py)이 설치 디렉터리에 있도록 하십시오. (ZIP 파일 내에서는 감지되지 않지만, 대신 올바른 이름의 ZIP 파일은 감지됨에 유의하십시오.)

이렇게 하면 시스템 전체 설치의 파일이 응용 프로그램과 함께 번들로 제공되는 표준 라이브러리의 복사본보다 우선하지 않습니다. 그렇지 않으면, 사용자가 여러분의 응용 프로그램을 사용하는 데 문제가 발생할 수 있습니다. 다른 제안은 레지스트리의 비표준 경로와 사용자 site-packages에 여전히 취약할 수 있어서, 첫 번째 제안이 가장 좋음에 유의하십시오.

버전 3.6에서 변경: ._pth 파일 지원을 추가하고 pyvenv.cfg에서 applocal 옵션을 제거합니다.

버전 3.6에서 변경: 실행 파일에 직접 인접할 때 잠재적인 랜드마크로 pythonXX.zip을 추가합니다.

버전 3.6부터 폐지됨: Modules(PythonPath가 아닙니다) 아래의 레지스트리에 지정된 모듈은 importlib.machinery.WindowsRegistryFinder 로 임포트 할 수 있습니다. 이 파인더는 윈도우 3.6.0과 이전 버전에서 활성화되지만, 향후에는 sys.meta_path에 명시적으로 추가해야 할 수도 있습니다.

4.9. 추가 모듈

파이썬이 모든 플랫폼 간에 이식성 있는 것을 목표로 하지만, 윈도우에만 고유한 기능이 있습니다. 이러한 기능을 사용하기 위한 표준 라이브러리와 외부에 있는 두 개의 모듈과 스니펫(snippets)이 존재합니다.

윈도우 특정 표준 모듈은 MS 윈도우 특정 서비스에 설명되어 있습니다.

4.9.1. PyWin32

Mark Hammond의 PyWin32 모듈은 고급 윈도우 특정 지원을 위한 모듈 모음입니다. 여기에는 다음을 위한 유틸리티가 포함됩니다:

PythonWin은 PyWin32와 함께 제공되는 샘플 MFC 응용 프로그램입니다. 디버거가 내장된 내장할 수 있는 IDE입니다.

더 보기

Win32 How Do I…?

저자: Tim Golden

Python and COM

저자: David와 Paul Boddie

4.9.2. cx_Freeze

cx_Freeze는 파이썬 스크립트를 실행 가능한 윈도우 프로그램(*.exe 파일)으로 래핑합니다. 이렇게 하면, 사용자가 파이썬을 설치할 필요 없는 응용 프로그램을 배포할 수 있습니다.

4.10. 윈도우에서 파이썬 컴파일하기

CPython을 직접 컴파일하려면, 먼저 소스를 가져와야 합니다. 최신 릴리스의 소스를 다운로드하거나 최신 버전을 체크아웃할 수 있습니다.

소스 트리에는 공식 파이썬 릴리스를 빌드하는 데 사용되는 컴파일러인 Microsoft Visual Studio 용 빌드 솔루션과 프로젝트 파일이 포함되어 있습니다. 이 파일들은 PCbuild 디렉터리에 있습니다.

빌드 프로세스에 대한 일반 정보는 PCbuild/readme.txt를 확인하십시오.

확장 모듈에 대해서는, 윈도우에서 C와 C++ 확장 빌드하기를 참조하십시오.

분실물 보관소