{{tag>[pipx python config environment-variable]}}

====== pipx Configuration ======
pipx의 저장 위치, 실행 파일 노출 위치, 기본 Python interpreter와 package backend를 환경변수로 설정하는 방법을 정리한다.

===== Summary =====
pipx는 별도 사용자 configuration file을 사용하지 않으며 모든 설정은 선택적 환경변수로 제공한다. 현재 적용값과 platform별 기본값은 고정 경로를 추측하지 말고 ''pipx environment''로 확인한다.

<code bash>
pipx environment
pipx environment --value PIPX_HOME
pipx environment --value PIPX_BIN_DIR
</code>

===== Environment Variables =====
  * ''PIPX_HOME'': 사용자별 virtual environment와 shared library data 위치를 지정한다.
  * ''PIPX_BIN_DIR'': 사용자별 application link 위치를 지정한다.
  * ''PIPX_MAN_DIR'': 사용자별 manual page link 위치를 지정한다.
  * ''PIPX_COMPLETION_DIR'': shell completion 설치 위치를 지정한다.
  * ''PIPX_GLOBAL_HOME'': ''--global'' 환경의 virtual environment 위치를 지정한다.
  * ''PIPX_GLOBAL_BIN_DIR'': ''--global'' application link 위치를 지정한다.
  * ''PIPX_GLOBAL_MAN_DIR'': ''--global'' manual page 위치를 지정한다.
  * ''PIPX_GLOBAL_COMPLETION_DIR'': ''--global'' shell completion 위치를 지정한다.
  * ''PIPX_SHARED_LIBS'': shared library directory를 지정한다.
  * ''PIPX_DEFAULT_PYTHON'': 새 환경에 사용할 기본 Python interpreter를 지정한다.
  * ''PIPX_DEFAULT_BACKEND'': 새 환경의 package backend를 ''pip'' 또는 ''uv''로 지정한다.
  * ''PIPX_FETCH_PYTHON'': 적합한 Python interpreter가 없을 때 standalone Python을 가져오는 정책을 지정한다.
  * <del>''PIPX_FETCH_MISSING_PYTHON''</del>: ''PIPX_FETCH_PYTHON=missing''의 deprecated alias이다.
  * ''PIPX_DISABLE_SHARED_LIBS_AUTO_UPGRADE'': shared library 자동 갱신을 비활성화한다.
  * ''PIPX_USE_EMOJI'': terminal 출력의 emoji 사용 여부를 제어한다.
  * ''PIPX_MAX_LOGS'': 보관할 log file 수를 지정한다.

===== Configuration =====
==== Shell session에 적용 ====
<code bash>
export PIPX_DEFAULT_PYTHON=python3.13
export PIPX_DEFAULT_BACKEND=uv
pipx install ruff
</code>

기존 virtual environment는 생성 당시 기록된 backend를 유지한다. 명시적으로 전환하려면 reinstall에서 backend를 지정한다.

<code bash>
pipx reinstall ruff --backend uv
</code>

==== 저장 경로 변경 ====
<code bash>
export PIPX_HOME="$XDG_DATA_HOME/pipx"
export PIPX_BIN_DIR="$HOME/.local/bin"
pipx ensurepath
</code>

<note warning>이미 설치된 환경이 있을 때 변수만 변경하면 기존 application이 자동으로 이동하지 않는다. 변경 전 ''pipx list''로 목록을 기록하고 공식 Move installation 절차를 확인한다.</note>

==== Private package index ====
pipx는 내부 installer에 ''PIP_*'' 환경변수를 전달한다. credential은 wiki, shell history, tracked file에 저장하지 않는다.

<code bash>
export PIP_INDEX_URL='https://packages.example.invalid/simple'
pipx install PACKAGE
</code>

일회성 설정은 ''--pip-args''로 전달할 수 있지만 token이나 password를 command line에 직접 쓰지 않는다.

===== Precedence =====
  - command line option이 해당 실행의 동작을 지정한다.
  - ''PIPX_*'' 환경변수가 pipx 기본 동작과 경로를 지정한다.
  - 값이 없으면 platform별 기본값을 사용한다.
  - 이미 존재하는 environment의 recorded backend는 새 기본 backend보다 우선한다.

===== Validation =====
<code bash>
pipx environment
pipx list
pipx health
</code>

===== Troubleshooting =====
  * ''PIPX_BIN_DIR''가 ''PATH''에 없으면 ''pipx ensurepath''를 실행하고 새 terminal을 연다.
  * system-wide 설정에서는 variable과 directory ownership을 함께 확인한다.
  * 설정 변경 뒤 package가 실행되지 않으면 ''pipx health''로 environment를 검사한다.

===== See Also =====
  * [[:python:pipx:ko]]
  * [[:python:pip]]
  * [[:python:venv]]
  * [[:python:uv]]
  * [[https://pipx.pypa.io/stable/how-to/configure-paths.html|Configure paths]]
  * [[https://pipx.pypa.io/stable/reference/environment-variables.html|Environment variables reference]]

===== History =====
  * codex:: 2026-08-16 pipx 경로, backend, Python 및 index 환경변수 설정을 정리함.

{{indexmenu>.#1|js}}