설정 파일¶
uv는 프로젝트와 사용자 수준에서 지속적인 설정 파일을 지원한다.
특히, uv는 현재 디렉터리나 가장 가까운 상위 디렉터리에서 pyproject.toml 또는 uv.toml 파일을 찾는다.
Note
사용자 수준에서 동작하는 tool 커맨드의 경우, 로컬 설정 파일은 무시된다. 대신 uv는 사용자 수준 설정(예: ~/.config/uv/uv.toml)과 시스템 수준 설정(예: /etc/uv/uv.toml)만 읽는다.
워크스페이스에서 uv는 워크스페이스 루트에서 검색을 시작하며, 워크스페이스 멤버에서 정의된 설정은 무시한다. 워크스페이스는 단일 단위로 잠기기 때문에 모든 멤버 간에 설정이 공유된다.
pyproject.toml 파일을 찾으면 uv는 [tool.uv] 테이블에서 설정을 읽는다. 예를 들어, 지속적인 인덱스 URL을 설정하려면 pyproject.toml에 다음을 추가한다:
[[tool.uv.index]]
url = "https://test.pypi.org/simple"
default = true
(해당 테이블이 없으면 pyproject.toml 파일은 무시되고, uv는 디렉터리 계층 구조에서 계속 검색한다.)
uv는 uv.toml 파일도 검색하며, 이 파일은 동일한 구조를 따르지만 [tool.uv] 접두사를 생략한다. 예를 들어:
[[index]]
url = "https://test.pypi.org/simple"
default = true
Note
uv.toml 파일은 pyproject.toml 파일보다 우선순위가 높다. 따라서 uv.toml과 pyproject.toml 파일이 동일한 디렉터리에 있으면 uv.toml에서 설정을 읽고, pyproject.toml의 [tool.uv] 섹션은 무시된다.
uv는 macOS와 Linux에서 ~/.config/uv/uv.toml(또는 $XDG_CONFIG_HOME/uv/uv.toml), Windows에서 %APPDATA%\uv\uv.toml에서 사용자 수준 설정을 찾는다. 또한 macOS와 Linux에서 /etc/uv/uv.toml(또는 $XDG_CONFIG_DIRS/uv/uv.toml), Windows에서 %SYSTEMDRIVE%\ProgramData\uv\uv.toml에서 시스템 수준 설정을 찾는다.
사용자 및 시스템 수준 설정은 uv.toml 형식을 사용해야 한다. pyproject.toml은 Python 프로젝트를 정의하기 위한 것이기 때문이다.
프로젝트, 사용자, 시스템 수준 설정 파일이 모두 발견되면 설정이 병합된다. 이때 프로젝트 수준 설정이 사용자 수준 설정보다 우선하고, 사용자 수준 설정이 시스템 수준 설정보다 우선한다. (여러 시스템 수준 설정 파일이 발견되면, 예를 들어 /etc/uv/uv.toml과 $XDG_CONFIG_DIRS/uv/uv.toml에서 모두 발견되면, XDG가 우선순위를 가지며 처음 발견된 파일만 사용된다.)
예를 들어, 문자열, 숫자, 불리언 값이 프로젝트와 사용자 수준 설정 테이블에 모두 존재하면 프로젝트 수준 값이 사용되고 사용자 수준 값은 무시된다. 배열이 두 테이블에 모두 존재하면 배열이 연결되며, 프로젝트 수준 설정이 병합된 배열의 앞쪽에 위치한다.
환경 변수를 통해 제공된 설정은 지속적인 설정보다 우선하며, 커맨드라인을 통해 제공된 설정은 둘 다보다 우선한다.
uv는 --no-config 커맨드라인 인수를 지원하며, 이 인수가 제공되면 모든 지속적인 설정 검색이 비활성화된다.
또한 uv는 --config-file 커맨드라인 인수를 지원하며, 이 인수는 uv.toml 파일의 경로를 받는다. 이 인수가 제공되면 이 파일이 모든 발견된 설정 파일 대신 사용된다(예: 사용자 수준 설정이 무시된다).
설정¶
사용 가능한 설정 항목에 대한 자세한 내용은 설정 참조를 참고한다.
.env¶
uv run은 dotenvy 크레이트를 통해 dotenv 파일(예: .env, .env.local, .env.development)에서 환경 변수를 불러올 수 있다.
특정 위치에서 .env 파일을 불러오려면 UV_ENV_FILE 환경 변수를 설정하거나 uv run에 --env-file 플래그를 전달한다.
예를 들어, 현재 작업 디렉토리에 있는 .env 파일에서 환경 변수를 불러오려면 다음과 같이 실행한다:
$ echo "MY_VAR='Hello, world!'" > .env
$ uv run --env-file .env -- python -c 'import os; print(os.getenv("MY_VAR"))'
Hello, world!
--env-file 플래그를 여러 번 제공할 수 있으며, 후속 파일은 이전 파일에 정의된 값을 덮어쓴다. UV_ENV_FILE 환경 변수를 통해 여러 파일을 제공하려면 경로를 공백으로 구분한다(예: UV_ENV_FILE="/path/to/file1 /path/to/file2").
dotenv 불러오기를 비활성화하려면(예: UV_ENV_FILE 또는 --env-file 커맨드라인 인수를 재정의하기 위해) UV_NO_ENV_FILE 환경 변수를 1로 설정하거나 uv run에 --no-env-file 플래그를 전달한다.
동일한 변수가 환경과 .env 파일에 모두 정의된 경우, 환경의 값이 우선한다.
pip 인터페이스 설정하기¶
uv pip 커맨드라인 인터페이스를 전용으로 설정하기 위해 [tool.uv.pip] 섹션이 제공된다. 이 섹션의 설정은 uv pip 네임스페이스 외부의 uv 명령어에는 적용되지 않는다. 하지만 이 섹션의 많은 설정들은 상위 네임스페이스에서도 동일하게 사용할 수 있으며, uv.pip 섹션에서 값을 재정의하지 않는 한 uv pip 인터페이스에도 적용된다.
uv.pip 설정은 pip의 인터페이스와 밀접하게 맞춰져 있으며, 전역 설정이 다른 설계(예: --no-build)를 사용할 수 있도록 별도로 선언되어 호환성을 유지한다.
예를 들어, 아래 pyproject.toml 파일에서 [tool.uv.pip] 아래에 index-url을 설정하면, uv pip 하위 명령어(예: uv pip install)에만 영향을 미치고 uv sync, uv lock, uv run에는 영향을 미치지 않는다:
[tool.uv.pip]
index-url = "https://test.pypi.org/simple"