Skip to content

Package indexesパッケージインデックス

By default, uv uses the Python Package Index (PyPI) for dependency resolution and package installation. However, uv can be configured to use other package indexes, including private indexes, via the [[tool.uv.index]] configuration option (and --index, the analogous command-line option).デフォルトでは、uvは依存関係の解決とパッケージのインストールにPython Package Index (PyPI)を使用します。しかし、uvは[[tool.uv.index]]設定オプション（および--index、同様のコマンドラインオプション）を介して、プライベートインデックスを含む他のパッケージインデックスを使用するように構成できます。

Defining an indexインデックスの定義

To include an additional index when resolving dependencies, add a [[tool.uv.index]] entry to your pyproject.toml:依存関係を解決する際に追加のインデックスを含めるには、pyproject.tomlに[[tool.uv.index]]エントリを追加します：

[[tool.uv.index]]
# Optional name for the index.
name = "pytorch"
# Required URL for the index.
url = "https://download.pytorch.org/whl/cpu"

Indexes are prioritized in the order in which they’re defined, such that the first index listed in the configuration file is the first index consulted when resolving dependencies, with indexes provided via the command line taking precedence over those in the configuration file.インデックスは定義された順序で優先され、設定ファイルにリストされた最初のインデックスが依存関係を解決する際に最初に参照されます。コマンドラインで提供されたインデックスは、設定ファイル内のインデックスよりも優先されます。

By default, uv includes the Python Package Index (PyPI) as the "default" index, i.e., the index used when a package is not found on any other index. To exclude PyPI from the list of indexes, set default = true on another index entry (or use the --default-index command-line option):デフォルトでは、uvはPython Package Index (PyPI)を「デフォルト」インデックスとして含めます。つまり、他のインデックスでパッケージが見つからない場合に使用されるインデックスです。PyPIをインデックスのリストから除外するには、別のインデックスエントリにdefault = trueを設定するか、--default-indexコマンドラインオプションを使用します：

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
default = true

The default index is always treated as lowest priority, regardless of its position in the list of indexes.デフォルトインデックスは、インデックスのリスト内の位置に関係なく、常に最低優先度として扱われます。

Index names may only contain alphanumeric characters, dashes, underscores, and periods, and must be valid ASCII.インデックス名には英数字、ダッシュ、アンダースコア、ピリオドのみを含めることができ、有効なASCIIでなければなりません。

When providing an index on the command line (with --index or --default-index) or through an environment variable (UV_INDEX or UV_DEFAULT_INDEX), names are optional but can be included using the <name>=<url> syntax, as in:コマンドラインでインデックスを提供する場合（--indexまたは--default-indexを使用）や環境変数（UV_INDEXまたはUV_DEFAULT_INDEX）を介して提供する場合、名前はオプションですが、<name>=<url>構文を使用して含めることができます。例：

# On the command line.
$ uv lock --index pytorch=https://download.pytorch.org/whl/cpu
# Via an environment variable.
$ UV_INDEX=pytorch=https://download.pytorch.org/whl/cpu uv lock

Pinning a package to an indexインデックスにパッケージをピン留めする

A package can be pinned to a specific index by specifying the index in its tool.uv.sources entry. For example, to ensure that torch is always installed from the pytorch index, add the following to your pyproject.toml:パッケージは、その tool.uv.sources エントリにインデックスを指定することで、特定のインデックスに固定できます。 例えば、torch が pytorch インデックスから 常に インストールされるようにするには、 次の内容を pyproject.toml に追加します：

[tool.uv.sources]
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"

Similarly, to pull from a different index based on the platform, you can provide a list of sources disambiguated by environment markers:同様に、プラットフォームに基づいて異なるインデックスから取得するには、環境マーカーで区別されたソースのリストを提供できます：

pyproject.toml
[project]
dependencies = ["torch"]

[tool.uv.sources]
torch = [
  { index = "pytorch-cu118", marker = "sys_platform == 'darwin'"},
  { index = "pytorch-cu124", marker = "sys_platform != 'darwin'"},
]

[[tool.uv.index]]
name = "pytorch-cu118"
url = "https://download.pytorch.org/whl/cu118"

[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://download.pytorch.org/whl/cu124"

An index can be marked as explicit = true to prevent packages from being installed from that index unless explicitly pinned to it. For example, to ensure that torch is installed from the pytorch index, but all other packages are installed from PyPI, add the following to your pyproject.toml:インデックスは explicit = true とマークされることで、そのインデックスからパッケージがインストールされるのを防ぎます。 明示的に固定されている場合を除きます。例えば、torch が pytorch インデックスからインストールされることを保証し、 他のすべてのパッケージが PyPI からインストールされるようにするには、次の内容を pyproject.toml に追加します：

[tool.uv.sources]
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

Named indexes referenced via tool.uv.sources must be defined within the project's pyproject.toml file; indexes provided via the command-line, environment variables, or user-level configuration will not be recognized.tool.uv.sources を介して参照される名前付きインデックスは、プロジェクトの pyproject.toml ファイル内で定義されている必要があります； コマンドライン、環境変数、またはユーザーレベルの設定を介して提供されたインデックスは認識されません。

If an index is marked as both default = true and explicit = true, it will be treated as an explicit index (i.e., only usable via tool.uv.sources) while also removing PyPI as the default index.インデックスが default = true と explicit = true の両方としてマークされている場合、それは明示的なインデックスとして扱われます（つまり、tool.uv.sources を介してのみ使用可能） 同時に PyPI をデフォルトインデックスから除外します。

Searching across multiple indexes複数のインデックスを横断して検索する

By default, uv will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index).デフォルトでは、uv は特定のパッケージが利用可能な最初のインデックスで停止し、その最初のインデックスに存在するものに解決を制限します（first-index）。

For example, if an internal index is specified via [[tool.uv.index]], uv's behavior is such that if a package exists on that internal index, it will always be installed from that internal index, and never from PyPI. The intent is to prevent "dependency confusion" attacks, in which an attacker publishes a malicious package on PyPI with the same name as an internal package, thus causing the malicious package to be installed instead of the internal package. See, for example, the torchtriton attack from December 2022.例えば、内部インデックスが [[tool.uv.index]] を介して指定されている場合、uv の動作は、 その内部インデックスにパッケージが存在する場合、常に その内部インデックスからインストールされ、 決して PyPI からはインストールされません。これは、攻撃者が内部パッケージと同じ名前の悪意のあるパッケージを PyPI に公開し、 内部パッケージの代わりに悪意のあるパッケージがインストールされる「依存関係の混乱」攻撃を防ぐことを目的としています。例えば、 2022年12月の torchtriton 攻撃 を参照してください。

To opt in to alternate index behaviors, use the--index-strategy command-line option, or the UV_INDEX_STRATEGY environment variable, which supports the following values:代替インデックスの動作を選択するには、--index-strategy コマンドラインオプション、または次の値をサポートする UV_INDEX_STRATEGY 環境変数を使用します：

  • first-index (default): Search for each package across all indexes, limiting the candidate versions to those present in the first index that contains the package.first-index（デフォルト）：すべてのインデックスを横断して各パッケージを検索し、候補バージョンをそのパッケージを含む最初のインデックスに存在するものに制限します。
  • unsafe-first-match: Search for each package across all indexes, but prefer the first index with a compatible version, even if newer versions are available on other indexes.unsafe-first-match: すべてのインデックスで各パッケージを検索しますが、互換性のあるバージョンがある場合は最初のインデックスを優先します。たとえ他のインデックスに新しいバージョンがあってもです。
  • unsafe-best-match: Search for each package across all indexes, and select the best version from the combined set of candidate versions.unsafe-best-match: すべてのインデックスで各パッケージを検索し、候補バージョンの組み合わせから最適なバージョンを選択します。

While unsafe-best-match is the closest to pip's behavior, it exposes users to the risk of "dependency confusion" attacks.unsafe-best-matchはpipの動作に最も近いですが、ユーザーを「依存関係の混乱」攻撃のリスクにさらします。

Authentication認証

Most private package indexes require authentication to access packages, typically via a username and password (or access token).ほとんどのプライベートパッケージインデックスは、通常はユーザー名とパスワード（またはアクセストークン）を介して、パッケージにアクセスするための認証を必要とします。

Tipヒント

See the alternative index guide for details on authenticating with specific private index providers, e.g., from AWS, Azure, or GCP.代替インデックスガイドを参照して、AWS、Azure、GCPなどの特定のプライベートインデックスプロバイダーとの認証の詳細を確認してください。

Providing credentials directly資格情報を直接提供する

Credentials can be provided directly via environment variables or by embedding them in the URL.資格情報は、環境変数を介して直接提供するか、URLに埋め込むことができます。

For example, given an index named internal-proxy that requires a username (public) and password (koala), define the index (without credentials) in your pyproject.toml:たとえば、ユーザー名（public）とパスワード（koala）を必要とするinternal-proxyという名前のインデックスがある場合、pyproject.tomlに資格情報なしでインデックスを定義します。

[[tool.uv.index]]
name = "internal-proxy"
url = "https://example.com/simple"

From there, you can set the UV_INDEX_INTERNAL_PROXY_USERNAME and UV_INDEX_INTERNAL_PROXY_PASSWORD environment variables, where INTERNAL_PROXY is the uppercase version of the index name, with non-alphanumeric characters replaced by underscores:そこから、UV_INDEX_INTERNAL_PROXY_USERNAMEとUV_INDEX_INTERNAL_PROXY_PASSWORDの環境変数を設定できます。ここで、INTERNAL_PROXYはインデックス名の大文字バージョンで、非英数字文字はアンダースコアに置き換えられます。

export UV_INDEX_INTERNAL_PROXY_USERNAME=public
export UV_INDEX_INTERNAL_PROXY_PASSWORD=koala

By providing credentials via environment variables, you can avoid storing sensitive information in the plaintext pyproject.toml file.環境変数を介して資格情報を提供することで、プレーンテキストのpyproject.tomlファイルに機密情報を保存するのを避けることができます。

Alternatively, credentials can be embedded directly in the index definition:代わりに、認証情報はインデックス定義に直接埋め込むことができます：

[[tool.uv.index]]
name = "internal"
url = "https://public:koala@pypi-proxy.corp.dev/simple"

For security purposes, credentials are never stored in the uv.lock file; as such, uv must have access to the authenticated URL at installation time.セキュリティ上の理由から、認証情報はuv.lockファイルに決して保存されません。そのため、uvはインストール時に認証されたURLにアクセスできる必要があります。

Using credential providers認証情報プロバイダーの使用

In addition to providing credentials directly, uv supports discovery of credentials from netrc and keyring. See the HTTP authentication documentation for details on setting up specific credential providers.認証情報を直接提供することに加えて、uvはnetrcおよびkeyringからの認証情報の発見をサポートしています。特定の認証情報プロバイダーの設定に関する詳細は、HTTP認証のドキュメントを参照してください。

By default, uv will attempt an unauthenticated request before querying providers. If the request fails, uv will search for credentials. If credentials are found, an authenticated request will be attempted.デフォルトでは、uvはプロバイダーに問い合わせる前に認証されていないリクエストを試みます。リクエストが失敗した場合、uvは認証情報を検索します。認証情報が見つかった場合、認証されたリクエストが試みられます。

Note注意

If a username is set, uv will search for credentials before making an unauthenticated request.ユーザー名が設定されている場合、uvは認証されていないリクエストを行う前に認証情報を検索します。

Some indexes (e.g., GitLab) will forward unauthenticated requests to a public index, like PyPI — which means that uv will not search for credentials. This behavior can be changed per-index, using the authenticate setting. For example, to always search for credentials:一部のインデックス（例：GitLab）は、認証されていないリクエストをPyPIのような公開インデックスに転送します。これは、uvが認証情報を検索しないことを意味します。この動作は、authenticate設定を使用してインデックスごとに変更できます。たとえば、常に認証情報を検索するには：

[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
authenticate = "always"

When authenticate is set to always, uv will eagerly search for credentials and error if credentials cannot be found.authenticateがalwaysに設定されている場合、uvは認証情報を積極的に検索し、認証情報が見つからない場合はエラーになります。

Ignoring error codes when searching across indexesインデックス間の検索時にエラーコードを無視する

When using the first-index strategy, uv will stop searching across indexes if an HTTP 401 Unauthorized or HTTP 403 Forbidden status code is encountered. The one exception is that uv will ignore 403s when searching the pytorch index (since this index returns a 403 when a package is not present).最初のインデックス戦略を使用する場合、uvはHTTP 401 UnauthorizedまたはHTTP 403 Forbiddenステータスコードに遭遇した場合、インデックス間の検索を停止します。唯一の例外は、uvがpytorchインデックスを検索する際に403を無視することです（このインデックスはパッケージが存在しない場合に403を返します）。

To configure which error codes are ignored for an index, use the ignored-error-codes setting. For example, to ignore 403s (but not 401s) for a private index:インデックスに対して無視されるエラーコードを設定するには、ignored-error-codes 設定を使用します。例えば、プライベートインデックスに対して403（ただし401は無視しない）を無視するには：

[[tool.uv.index]]
name = "private-index"
url = "https://private-index.com/simple"
authenticate = "always"
ignore-error-codes = [403]

uv will always continue searching across indexes when it encounters a 404 Not Found. This cannot be overridden.uvは、404 Not Found に遭遇したとき、常にインデックスを横断して検索を続けます。これはオーバーライドできません。

Disabling authentication認証の無効化

To prevent leaking credentials, authentication can be disabled for an index:資格情報の漏洩を防ぐために、インデックスの認証を無効にすることができます：

[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
authenticate = "never"

When authenticate is set to never, uv will never search for credentials for the given index and will error if credentials are provided directly.authenticate が never に設定されている場合、uvは指定されたインデックスのために資格情報を検索せず、資格情報が直接提供された場合はエラーになります。

Customizing cache control headersキャッシュ制御ヘッダーのカスタマイズ

By default, uv will respect the cache control headers provided by the index. For example, PyPI serves package metadata with a max-age=600 header, thereby allowing uv to cache package metadata for 10 minutes; and wheels and source distributions with a max-age=365000000, immutable header, thereby allowing uv to cache artifacts indefinitely.デフォルトでは、uvはインデックスによって提供されたキャッシュ制御ヘッダーを尊重します。例えば、PyPIはパッケージメタデータを max-age=600 ヘッダーで提供し、これによりuvはパッケージメタデータを10分間キャッシュできます。また、ホイールとソース配布は max-age=365000000, immutable ヘッダーで提供され、これによりuvはアーティファクトを無期限にキャッシュできます。

To override the cache control headers for an index, use the cache-control setting:インデックスのキャッシュ制御ヘッダーをオーバーライドするには、cache-control 設定を使用します：

[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
cache-control = { api = "max-age=600", files = "max-age=365000000, immutable" }

The cache-control setting accepts an object with two optional keys:cache-control 設定は、2つのオプションキーを持つオブジェクトを受け入れます：

  • api: Controls caching for Simple API requests (package metadata).api: シンプルAPIリクエスト（パッケージメタデータ）のキャッシュを制御します。
  • files: Controls caching for artifact downloads (wheels and source distributions).files: アーティファクトのダウンロード（ホイールとソース配布）のキャッシュ制御を行います。

The values for these keys are strings that follow the HTTP Cache-Control syntax. For example, to force uv to always revalidate package metadata, set api = "no-cache":これらのキーの値は文字列で、 HTTP Cache-Control 構文に従います。例えば、uvにパッケージメタデータを常に再検証させるには、api = "no-cache"を設定します:

[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
cache-control = { api = "no-cache" }

This setting is most commonly used to override the default cache control headers for private indexes that otherwise disable caching, often unintentionally. We typically recommend following PyPI's approach to caching headers, i.e., setting api = "max-age=600" and files = "max-age=365000000, immutable".この設定は、キャッシュを無効にするプライベートインデックスのデフォルトのキャッシュ制御ヘッダーを上書きするために最も一般的に使用されますが、しばしば意図せずに行われます。通常、PyPIのキャッシュヘッダーのアプローチに従うことを推奨します。つまり、api = "max-age=600"と files = "max-age=365000000, immutable"を設定します。

"Flat" indexes"フラット" インデックス

By default, [[tool.uv.index]] entries are assumed to be PyPI-style registries that implement the PEP 503 Simple Repository API. However, uv also supports "flat" indexes, which are local directories or HTML pages that contain flat lists of wheels and source distributions. In pip, such indexes are specified using the --find-links option.デフォルトでは、[[tool.uv.index]] エントリは、 PEP 503 シンプルリポジトリAPIを実装するPyPIスタイルのレジストリであると見なされます。しかし、uvは"フラット"インデックスもサポートしており、これはホイールとソース配布のフラットリストを含むローカルディレクトリまたはHTMLページです。pipでは、そのようなインデックスは--find-linksオプションを使用して指定されます。

To define a flat index in your pyproject.toml, use the format = "flat" option:pyproject.tomlでフラットインデックスを定義するには、format = "flat"オプションを使用します:

[[tool.uv.index]]
name = "example"
url = "/path/to/directory"
format = "flat"

Flat indexes support the same feature set as Simple Repository API indexes (e.g., explicit = true); you can also pin a package to a flat index using tool.uv.sources.フラットインデックスは、シンプルリポジトリAPIインデックスと同じ機能セットをサポートします（例：explicit = true）。また、tool.uv.sourcesを使用してパッケージをフラットインデックスに固定することもできます。

--index-url and --extra-index-url--index-url と --extra-index-url

In addition to the [[tool.uv.index]] configuration option, uv supports pip-style --index-url and --extra-index-url command-line options for compatibility, where --index-url defines the default index and --extra-index-url defines additional indexes.[[tool.uv.index]]構成オプションに加えて、uvはpipスタイルの--index-urlと --extra-index-urlコマンドラインオプションを互換性のためにサポートしており、--index-urlはデフォルトのインデックスを定義し、--extra-index-urlは追加のインデックスを定義します。

These options can be used in conjunction with the [[tool.uv.index]] configuration option, and follow the same prioritization rules:これらのオプションは、[[tool.uv.index]]構成オプションと併用でき、同じ優先順位ルールに従います:

  • The default index is always treated as lowest priority, whether defined via the legacy --index-url argument, the recommended --default-index argument, or a [[tool.uv.index]] entry with default = true.デフォルトのインデックスは、レガシーの --index-url 引数、推奨される --default-index 引数、または [[tool.uv.index]] エントリで default = true が設定されている場合でも、常に最低優先度として扱われます。
  • Indexes are consulted in the order in which they’re defined, either via the legacy --extra-index-url argument, the recommended --index argument, or [[tool.uv.index]] entries.インデックスは、レガシーの --extra-index-url 引数、推奨される --index 引数、または [[tool.uv.index]] エントリで定義された順序で参照されます。

In effect, --index-url and --extra-index-url can be thought of as unnamed [[tool.uv.index]] entries, with default = true enabled for the former. In that context, --index-url maps to --default-index, and --extra-index-url maps to --index.実際には、--index-url と --extra-index-url は、名前のない [[tool.uv.index]] エントリとして考えることができ、前者には default = true が有効になっています。その文脈では、--index-url は --default-index に、--extra-index-url は --index に対応します。