Virtual environment¶仮想環境¶
This uses virtual environments backed by virtualenv or UV.これは、virtualenv または UV によってバックアップされた仮想環境を使用します。
Configuration¶設定¶
The environment plugin name is virtual.環境プラグイン名は virtual です。
[tool.hatch.envs.<ENV_NAME>]
type = "virtual"
[envs.<ENV_NAME>]
type = "virtual"
Options¶オプション¶
| Optionオプション | Defaultデフォルト | Description説明 |
|---|---|---|
pythonpython | The version of Python to find on your system and subsequently use to create the environment, defaulting to the HATCH_PYTHON environment variable, followed by the normal resolution logic. Setting the HATCH_PYTHON environment variable to self will force the use of the Python executable Hatch is running on. For more information, see the documentation.システム上で見つけるPythonのバージョンで、環境を作成するために使用され、デフォルトでは HATCH_PYTHON 環境変数に従い、その後 通常の解決ロジック に従います。 HATCH_PYTHON 環境変数を self に設定すると、Hatchが実行しているPython実行可能ファイルの使用が強制されます。詳細については、ドキュメントを参照してください。 | |
python-sourcespython-sources | ['external', 'internal']['external', 'internal'] | This may be set to an array of strings that are either the literal internal or external. External considers only Python executables that are already on PATH. Internal considers only internally managed Python distributions.これは、リテラルの internal または external のいずれかである文字列の配列に設定できます。Externalは、PATH に既にあるPython実行可能ファイルのみを考慮します。Internalは、内部管理されたPythonディストリビューション のみを考慮します。 |
pathpath | An explicit path to the virtual environment. The path may be absolute or relative to the project root. Any environments that inherit this option will also use this path. The environment variable HATCH_ENV_TYPE_VIRTUAL_PATH may be used, which will take precedence.仮想環境への明示的なパス。パスはプロジェクトルートに対して絶対または相対である可能性があります。このオプションを継承する環境もこのパスを使用します。環境変数 HATCH_ENV_TYPE_VIRTUAL_PATH を使用することができ、これが優先されます。 | |
system-packagessystem-packages | falsefalse | Whether or not to give the virtual environment access to the system site-packages directory仮想環境にシステムの site-packages ディレクトリへのアクセスを与えるかどうか |
installerinstaller | pippip | When set to uv, UV will be used in place of virtualenv & pip for virtual environment creation and dependency management, respectively. If you intend to provide UV yourself, you may set the HATCH_ENV_TYPE_VIRTUAL_UV_PATH environment variable which should be the absolute path to a UV binary. This environment variable implicitly sets the installer option to uv (if unset).uv に設定されている場合、UV が仮想環境の作成と依存関係管理のために virtualenv と pip の代わりに使用されます。自分で UV を提供するつもりがある場合は、HATCH_ENV_TYPE_VIRTUAL_UV_PATH 環境変数を設定することができ、これは UV バイナリへの絶対パスである必要があります。この環境変数は、installer オプションを uv に暗黙的に設定します（未設定の場合）。 |
Location¶場所¶
The location of environments is determined in the following heuristic order:環境の場所は、以下のヒューリスティックな順序で決定されます：
- The
pathoptionpathオプション - A directory named after the environment within the configured
virtualenvironment directory if the directory resides somewhere within the project root or if it is set to a.virtualenvsdirectory within the user's home directoryプロジェクトのルート内にディレクトリが存在する場合、またはユーザーのホームディレクトリ内の.virtualenvsディレクトリに設定されている場合、設定されたvirtual環境ディレクトリ 内に環境にちなんだ名前のディレクトリ - Otherwise, environments are stored within the configured
virtualenvironment directory in a deeply nested structure in order to support multiple projectsそうでない場合、環境は設定されたvirtual環境ディレクトリ 内に、複数のプロジェクトをサポートするために深くネストされた構造で保存されます
Additionally, when the path option is not used, the name of the directory for the default environment will be the normalized project name to provide a more meaningful default shell prompt.さらに、path オプションが使用されていない場合、default 環境のディレクトリ名は、より意味のあるデフォルトのシェル プロンプトを提供するために正規化されたプロジェクト名になります。
Python resolution¶Pythonの解決¶
Virtual environments necessarily require a parent installation of Python. The following rules determine how the parent is resolved.仮想環境は必ず親のPythonインストールを必要とします。以下のルールが親の解決方法を決定します。
The Python choice is determined by the python option followed by the HATCH_PYTHON environment variable. If the choice is via the environment variable, then resolution stops and that path is used unconditionally.Pythonの選択は、pythonオプションと続いてHATCH_PYTHON環境変数によって決まります。環境変数を介して選択された場合、解決は停止し、そのパスが無条件に使用されます。
The resolvers will be based on the python-sources option and all resolved interpreters will ensure compatibility with the project's defined Python support.リゾルバーは、python-sourcesオプションに基づき、すべての解決されたインタプリタはプロジェクトで定義されたPythonサポートとの互換性を確保します。
If a Python version has been chosen then each resolver will try to find an interpreter that satisfies that version.Pythonのバージョンが選択された場合、各リゾルバーはそのバージョンを満たすインタプリタを見つけようとします。
If no version has been chosen, then each resolver will try to find a version that matches the version of Python that Hatch is currently running on. If not found then each resolver will try to find the highest compatible version.バージョンが選択されていない場合、各リゾルバーはHatchが現在実行しているPythonのバージョンに一致するバージョンを見つけようとします。見つからない場合、各リゾルバーは最高の互換性のあるバージョンを見つけようとします。
Note注意
Some external Python paths are considered unstable and are ignored during resolution. For example, if Hatch is installed via Homebrew then sys.executable will be ignored because the interpreter could change or be removed at any time.いくつかの外部Pythonパスは不安定と見なされ、解決中に無視されます。たとえば、HatchがHomebrewを介してインストールされている場合、sys.executableは無視されます。なぜなら、インタプリタはいつでも変更されたり削除されたりする可能性があるからです。
Note注意
When resolution finds a match using an internally managed distribution and an update is available, the latest distribution will automatically be downloaded before environment creation.解決が内部管理されたディストリビューションを使用して一致を見つけ、更新が利用可能な場合、最新のディストリビューションが環境作成の前に自動的にダウンロードされます。
Internal distributions¶内部ディストリビューション¶
The following options are recognized for internal Python resolution.内部Python解決のために認識されるオプションは以下の通りです。
Tipヒント
You can set custom sources for distributions by setting the HATCH_PYTHON_SOURCE_<NAME> environment variable where <NAME> is the uppercased version of the distribution name with periods replaced by underscores e.g. HATCH_PYTHON_SOURCE_PYPY3_10.配布物のカスタムソースを設定するには、HATCH_PYTHON_SOURCE_<NAME> 環境変数を設定します。ここで、<NAME> は配布物名の大文字バージョンで、ピリオドをアンダースコアに置き換えたものです。例えば、HATCH_PYTHON_SOURCE_PYPY3_10のようになります。
CPython¶CPython¶
| NAME名前 |
|---|
3.7 |
3.8 |
3.9 |
3.10 |
3.11 |
3.12 |
3.13 |
The source of distributions is the python-build-standalone project.配布のソースはpython-build-standaloneプロジェクトです。
Some distributions have variants that may be configured with environment variables. Options may be combined.一部の配布には、環境変数で構成できるバリアントがあります。オプションは組み合わせることができます。
| Optionオプション | Platformsプラットフォーム | Allowed values許可される値 |
|---|---|---|
HATCH_PYTHON_VARIANT_CPUHATCH_PYTHON_VARIANT_CPU |
|
|
HATCH_PYTHON_VARIANT_GILHATCH_PYTHON_VARIANT_GIL |
|
|
PyPy¶PyPy¶
| NAME名前 |
|---|
pypy2.7pypy2.7 |
pypy3.9pypy3.9 |
pypy3.10pypy3.10 |
The source of distributions is the PyPy project.配布のソースはPyPyプロジェクトです。
Troubleshooting¶トラブルシューティング¶
macOS SIP¶macOS SIP¶
If you need to set linker environment variables like those starting with DYLD_ or LD_, any executable secured by System Integrity Protection that is invoked when running commands will not see those environment variable modifications as macOS strips those.もしDYLD_やLD_で始まるリンカ環境変数を設定する必要がある場合、System Integrity Protectionによって保護された実行可能ファイルは、コマンドを実行する際にそれらの環境変数の変更を認識しません。macOSがそれらを削除するためです。
Hatch interprets such commands as shell commands but deliberately ignores such paths to protected shells. This workaround suffices for the majority of use cases but there are 2 situations in which it may not:Hatchはそのようなコマンドをシェルコマンドとして解釈しますが、意図的に保護されたシェルへのパスを無視します。この回避策はほとんどの使用ケースには十分ですが、2つの状況ではそうではない場合があります:
- There are no unprotected
sh,bash,zsh, norfishexecutables found along PATH.PATHに保護されていないsh、bash、zsh、またはfishの実行可能ファイルは見つかりませんでした。 - The desired executable is a project's script, and the location of environments contains spaces or is longer than 1241 characters. In this case
pipand other installers will create such an entry point with a shebang pointing to/bin/sh(which is protected) to avoid shebang limitations. Rather than changing the location, you could invoke the script as e.g.python -m pytest(if the project supports that method of invocation by shipping a__main__.py).目的の実行可能ファイルはプロジェクトのスクリプトであり、環境の場所にスペースが含まれているか、1241文字を超えています。この場合、pipや他のインストーラーは、/bin/sh（保護されています）を指すシェバンを持つエントリポイントを作成します。場所を変更する代わりに、例えばpython -m pytestとしてスクリプトを呼び出すことができます（プロジェクトが__main__.pyを提供している場合）。