Configuration

Poetryはconfigコマンド(see more about its usage here)で設定することも、config.tomlファイルで直接設定することもできます。config.tomlファイルは、そのコマンドを最初に実行したときに自動的に作成されます。このファイルは通常、次のいずれかのディレクトリにあります。

macOS: ~/Library/Application Support/pypoetry
Windows: %APPDATA%\pypoetry

Unixでは、XDG仕様に従い、$XDG_CONFIG_HOMEをサポートしています。つまり、デフォルトでは~/.config/pypoetryです。

Local configuration

Poetryには、configコマンドに--localオプションを渡すことで、プロジェクト固有の設定を行う機能もあります。

poetry config virtualenvs.create false --local

Note

Poetryアプリケーションのローカル設定は、pyproject.tomlとは別のpoetry.tomlファイルに保存されます。

Warning

このファイルにはユーザー固有の情報や機密情報が含まれている可能性があるため、リポジトリにチェックインする際には注意が必要です。

Listing the current configuration

現在の設定を一覧表示するには、configコマンドの--listオプションを使用します。

poetry config --list

次のような結果になります

cache-dir = "/path/to/cache/directory"
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = true
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}/virtualenvs"  # /path/to/cache/directory/virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"

Displaying a single configuration setting

特定の設定の値を確認したい場合は、configコマンドにその名前を指定します。

poetry config virtualenvs.path

サポートされている設定の完全なリストについては、Available settingsを参照してください。

Adding or updating a configuration setting

新しい構成設定を変更または追加するには、設定の名前の後に値を渡します。

poetry config virtualenvs.path /path/to/cache/directory/virtualenvs

サポートされている設定の完全なリストについては、Available settingsを参照してください。

Removing a specific setting

以前に設定された設定を削除したい場合は、--unsetオプションを使用できます。

poetry config virtualenvs.path --unset

その後、設定のデフォルト値が取得されます。

Using environment variables

時には、特にCIツールでPoetryを使用する場合、環境変数を使用する方が簡単で、コンフィギュレーションコマンドを実行する必要がありません。

Poetryはこれをサポートしており、環境変数を使用して任意の設定を行うことができます。

環境変数の先頭にはPOETRY_を付ける必要があります。環境変数は大文字の設定名で構成され、ドットとダッシュはアンダースコアに置き換えられます。次に例を示します。

export POETRY_VIRTUALENVS_PATH=/path/to/virtualenvs/directory

これは、資格情報などのシークレット設定にも有効です。

export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret

Default Directories

Poetryは、次のデフォルトディレクトリを使用します。

Config Directory

Linux: $XDG_CONFIG_HOME/pypoetry または ~/.config/pypoetry
Windows: %APPDATA%\pypoetry
macOS: ~/Library/Application Support/pypoetry

POETRY_CONFIG_DIR環境変数を設定することで、Configディレクトリを上書きできます。

Data Directory

Linux: $XDG_DATA_HOME/pypoetry または ~/.local/share/pypoetry
Windows: %APPDATA%\pypoetry
macOS: ~/Library/Application Support/pypoetry

POETRY_DATA_DIRまたはPOETRY_HOME環境変数を設定することで、データディレクトリを上書きすることができます。POETRY_HOMEが設定されている場合、より高い優先度が与えられます。

Cache Directory

Linux: $XDG_CACHE_HOME/pypoetry または ~/.cache/pypoetry
Windows: %LOCALAPPDATA%\pypoetry
macOS: ~/Library/Caches/pypoetry

POETRY_CACHE_DIR環境変数を設定することで、キャッシュディレクトリを上書きできます。

Available settings

`cache-dir`

Type: string

Environment Variable: POETRY_CACHE_DIR

Poetryで使用されるキャッシュ・ディレクトリへのパス。

デフォルトでは、次のいずれかのディレクトリになります。

macOS: ~/Library/Caches/pypoetry
Windows: C:\Users\<username>\AppData\Local\pypoetry\Cache
Unix: ~/.cache/pypoetry

`experimental.system-git-client`

Type: boolean

Default: false

Environment Variable: POETRY_EXPERIMENTAL_SYSTEM_GIT_CLIENT

Introduced in 1.2.0

git関連のタスクには、system git client backendを使用します。

Poetryは、gitクライアントの可用性に依存しないように、git関連のタスクにデフォルトでdulwichを使用します。

何らかの問題が発生した場合は、trueに設定してシステムのgitバックエンドを使用してください。

`installer.max-workers`

Type: int

Default: number_of_cores + 4

Environment Variable: POETRY_INSTALLER_MAX_WORKERS

Introduced in 1.2.0

パラレルインストーラの使用中にワーカの最大数を設定します。 number_of_coresはos.cpu_count()によって決定されます。 NotImplementedError例外が発生した場合、number_of_coresは1と見なされます。

この設定パラメータがnumber_of_cores+4より大きい値に設定されている場合でも、最大ワーカー数はnumber_of_cores+4に制限されます。

Note

installer.parallelがfalseに設定されている場合、この設定は無視されます。

`installer.no-binary`

Type: string | boolean

Default: false

Environment Variable: POETRY_INSTALLER_NO_BINARY

Introduced in 1.2.0

この構成を設定すると、すべてのパッケージ、すべてのパッケージ、または特定のパッケージに対して、バイナリ配布フォーマットの使用を禁止できます。

Configuration	Description
`:all:` or `true`	すべてのパッケージでバイナリ配布を禁止します。
`:none:` or `false`	すべてのパッケージにバイナリ配布を許可します。
`package[,package,..]`	指定されたパッケージに対してのみバイナリ配布を禁止します

Note

ここで説明するすべての構成と同様に、これはユーザー固有の構成です。つまり、ロックファイルが生成されたり、依存関係が解決されたりするときには、これは考慮されません。これは、Poetry管理環境にインストールする依存関係のディストリビューションを選択する場合にのみ適用されます。

Note

プロジェクト固有の使用法では、--localで設定することをお勧めします。

poetry config --local installer.no-binary :all:

Note

environment variableを使用してCIまたはコンテナ環境を設定する場合に便利です。

export POETRY_INSTALLER_NO_BINARY=:all:

Warning

これがシステム全体で必要とされない限り、グローバルに設定されている場合、誤って設定すると、すべてのプロジェクトでインストール時間が遅くなる可能性があります。

`installer.only-binary`

Type: string | boolean

Default: false

Environment Variable: POETRY_INSTALLER_ONLY_BINARY

Introduced in 1.9.0

この構成を設定すると、すべてのパッケージ、パッケージなし、または特定のパッケージに対して、バイナリ配布形式の使用を強制できます。

Note

使用可能な値、使用方法、および警告については、installer.no-binaryを参照してください。

`installer.parallel`

Type: boolean

Default: true

Environment Variable: POETRY_INSTALLER_PARALLEL

Introduced in 1.1.4

新しい(>=1.1.0)インストーラを使用する場合は、並列実行を使用してください。

`solver.lazy-wheel`

Type: boolean

Default: true

Environment Variable: POETRY_SOLVER_LAZY_WHEEL

Introduced in 1.8.0

Wheel全体をダウンロードしてメタデータを抽出するのではなく、HTTP range requestsを使用してWheelのMETADATAファイルのみをダウンロードします。特に低速なネットワーク接続では、この設定によって依存関係の解決を大幅に高速化できます。キャッシュがすでにいっぱいになっている場合、またはサーバがHTTP範囲要求をサポートしていない場合は、この設定では違いはありません。

`virtualenvs.create`

Type: boolean

Default: true

Environment Variable: POETRY_VIRTUALENVS_CREATE

仮想環境が存在しない場合は、新しい仮想環境を作成します。

falseに設定すると、Poetryは新しい仮想環境を作成しません。すでに有効になっている仮想環境、または{cache-dir}/virtualenvsや{project-dir}/.venvに既存の仮想環境が検出された場合は、そこに依存関係がインストールされます。それ以外の場合は、システムのpython環境に依存関係がインストールされます。

Note

Poetryは、起動された仮想環境内で実行されていることを検出すると、virtualenvs.createに設定されている値にかかわらず、新しい仮想環境を作成しません。

Note

依存関係をシステム環境にインストールすると、既存のパッケージがアップグレードまたはアンインストールされ、他のアプリケーションが破損する可能性があることに注意してください。プロジェクトのインストール後に追加のPythonパッケージをインストールすると、Poetryプロジェクトが破損する可能性があります。

これが、常に仮想環境を作成することが推奨される理由です。これは、追加のPythonパッケージも含まれる可能性があるため、Dockerコンテナにも当てはまります。

`virtualenvs.in-project`

Type: boolean

Default: None

Environment Variable: POETRY_VIRTUALENVS_IN_PROJECT

プロジェクトのルートディレクトリ内にvirtualenvを作成します。

明示的に設定されていない場合、poetryはデフォルトで{cache-dir}/virtualenvsの下に仮想環境を作成するか、すでに存在する場合は{project-dir}/.venvディレクトリを使用します。

trueに設定すると、プロジェクトのルートディレクトリ内の.venvという名前のフォルダにvirtualenvが作成されます。

Note

プロジェクトの仮想環境がすでに{cache-dir}/virtualenvsの下に作成されている場合、この変数をtrueに設定しても、poetryはローカル仮想環境を作成したり使用したりしません。

すでにその状態にあるプロジェクトに対してこの設定を有効にするには、{cache-dir}/virtualenvsにある仮想環境フォルダを削除する必要があります。

現在のプロジェクトの仮想環境(もしあれば)がどこに保存されているかは、poetry env info--pathコマンドで調べることができます。

falseに設定すると、poetryは既存の.venvディレクトリを無視します。

`virtualenvs.options.always-copy`

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_ALWAYS_COPY

Introduced in 1.2.0

trueに設定すると、仮想環境の作成時に--always-copyパラメータがvirtualenvに渡され、必要なすべてのファイルがシンボリックリンクではなくvirtualenvにコピーされます。

`virtualenvs.options.no-pip`

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_NO_PIP

Introduced in 1.2.0

trueに設定すると、仮想環境の作成時に--no-pipパラメータがvirtualenvに渡されます。これは、新しい仮想環境が作成されたときに、pipが環境にインストールされないことを意味します。

Note

Poetryは、その内部操作のために、Poetryの実行環境に依存関係としてインストールされたvirtualenvパッケージに埋め込まれたpipホイールを使用します。このオプションがtrueに設定されているときにユーザーがpoetry run pipを実行すると、pipの埋め込まれたインスタンスであるpipが使用されます。

追加パッケージのない仮想環境を希望する場合は、no-setuptoolsとともに、これをtrueに設定しても問題ありません。これは本番環境に適しています。

`virtualenvs.options.no-setuptools`

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_NO_SETUPTOOLS

Introduced in 1.2.0

trueに設定されている場合、仮想環境の作成時に--no-setuptoolsパラメータがvirtualenvに渡されます。これは、新しい仮想環境が作成されても、その環境にsetuptoolsがインストールされないことを意味します。 Poetryは、その内部操作のためにsetuptoolsを必要とせず、これはtrueに安全に設定できます。

Python 3.12以降を使用する環境では、virtualenvはデフォルトで、仮想環境の作成時にsetuptoolsをインストールしません。したがって、このような環境では、このPoetry設定オプションは効果がありません。 setuptoolsはどちらの方法でもインストールされません。プロジェクトがsetuptoolsに依存している場合は、依存関係として宣言する必要があります。

Warning

IDEなどの一部の開発ツールでは、setuptools(およびその他の)パッケージが仮想環境内に常に存在し、利用可能であることを前提としています。これにより、このツールの一部の機能が期待どおりに動作しない可能性があります。

`virtualenvs.options.system-site-packages`

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_OPTIONS_SYSTEM_SITE_PACKAGES

仮想環境にsystem site-packagesディレクトリへのアクセス権を付与します。 virtualenvの作成時に適用されます。

`virtualenvs.path`

Type: string

Default: {cache-dir}/virtualenvs

Environment Variable: POETRY_VIRTUALENVS_PATH

Directory where virtual environments will be created.

Note

この設定は、グローバルな仮想環境の保存パスを制御します。ほとんどの場合、ローカルレベルでは役に立ちません。仮想環境をプロジェクトルートに保存するには、virtualenvs.in-projectを参照してください。

`virtualenvs.prefer-active-python` (experimental)

Type: boolean

Default: false

Environment Variable: POETRY_VIRTUALENVS_PREFER_ACTIVE_PYTHON

Introduced in 1.2.0

現在アクティブなPythonバージョンを使用して、新しい仮想環境を作成します。 falseに設定すると、Poetryのインストール時に使用されたPythonバージョンが使用されます。

`virtualenvs.prompt`

Type: string

Default: {project_name}-py{python_version}

Environment Variable: POETRY_VIRTUALENVS_PROMPT

Introduced in 1.2.0

仮想環境がアクティブ化されたときに表示されるプロンプトを定義するフォーマット文字列。フォーマットには変数project_nameとpython_versionを使用できます。

`repositories.<name>.url`

Type: string

Environment Variable: POETRY_REPOSITORIES_<NAME>_URL

<name>のリポジトリURLを設定します。

詳細については、Publishable Repositoriesを参照してください。

`http-basic.<name>.[username|password]`:

Type: string

Environment Variables: POETRY_HTTP_BASIC_<NAME>_USERNAME, POETRY_HTTP_BASIC_<NAME>_PASSWORD

<name>のリポジトリ認証情報(usernameとpassword)を設定します。詳細については、Repositories-Configuring credentialsを参照してください。

`pypi-token.<name>`:

Type: string

Environment Variable: POETRY_PYPI_TOKEN_<NAME>

<name>のリポジトリ認証情報を(APIトークンを使って)設定します。詳細については、Repositories-Configuring credentialsを参照してください。

`certificates.<name>.cert`:

Type: string | boolean

Environment Variable: POETRY_CERTIFICATES_<NAME>_CERT

リポジトリ<name>のカスタム認証局を設定します。詳細については、Repositories-Configuring credentials-Custom certificate authorityを参照してください。

このリポジトリに対してTLS証明書の検証をスキップする必要がある場合は、この設定を"false"に設定できます。

`certificates.<name>.client-cert`:

Type: string

Environment Variable: POETRY_CERTIFICATES_<NAME>_CLIENT_CERT

詳細については、Repositories-Configuring credentials-Custom certificate authorityを参照してください。

`keyring.enabled`:

Type: boolean

Default: true

Environment Variable: POETRY_KEYRING_ENABLED

See Repositories - Configuring credentials for more information. 認証情報を保存するためのシステムキーリングを有効にします。詳細については、Repositories-Configuring credentialsを参照してください。

Configuration

Local configuration

Listing the current configuration

Displaying a single configuration setting

Adding or updating a configuration setting

Removing a specific setting

Using environment variables

Default Directories

Config Directory

Data Directory

Cache Directory

Available settings

cache-dir

experimental.system-git-client

installer.max-workers

installer.no-binary

installer.only-binary

installer.parallel

solver.lazy-wheel

virtualenvs.create

virtualenvs.in-project

virtualenvs.options.always-copy

virtualenvs.options.no-pip

virtualenvs.options.no-setuptools

virtualenvs.options.system-site-packages

virtualenvs.path

virtualenvs.prefer-active-python (experimental)

virtualenvs.prompt

repositories.<name>.url

http-basic.<name>.[username|password]:

pypi-token.<name>:

certificates.<name>.cert:

certificates.<name>.client-cert:

keyring.enabled:

`cache-dir`

`experimental.system-git-client`

`installer.max-workers`

`installer.no-binary`

`installer.only-binary`

`installer.parallel`

`solver.lazy-wheel`

`virtualenvs.create`

`virtualenvs.in-project`

`virtualenvs.options.always-copy`

`virtualenvs.options.no-pip`

`virtualenvs.options.no-setuptools`

`virtualenvs.options.system-site-packages`

`virtualenvs.path`

`virtualenvs.prefer-active-python` (experimental)

`virtualenvs.prompt`

`repositories.<name>.url`

`http-basic.<name>.[username|password]`:

`pypi-token.<name>`:

`certificates.<name>.cert`:

`certificates.<name>.client-cert`:

`keyring.enabled`: