設定

設定 #

Poetryは、configコマンド（詳細はこちらを参照）または、最初にそのコマンドを実行したときに自動的に作成されるconfig.tomlファイルで直接設定できます。このファイルは通常、次のいずれかのディレクトリにあります。

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

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

ローカル設定 #

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

poetry config virtualenvs.create false --local

注意

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

警告

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

現在の設定を一覧表示する #

現在の設定を一覧表示するには、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}"

単一の設定を表示する #

特定の設定の値を確認したい場合は、その名前をconfigコマンドに渡すことができます。

poetry config virtualenvs.path

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

設定の追加または更新 #

設定を変更したり、新しい設定を追加したりするには、設定名の後に値を渡すことができます。

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

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

特定の設定を削除する #

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

poetry config virtualenvs.path --unset

設定はデフォルト値に戻ります。

環境変数の使用 #

特にCIツールでPoetryを使用する場合、構成コマンドを実行するのではなく、環境変数を使用する方が簡単な場合があります。

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

環境変数はPOETRY_をプレフィックスとし、設定の名前を大文字にし、ドットとダッシュをアンダースコアに置き換えたもので構成されます。以下に例を示します。

export POETRY_VIRTUALENVS_PATH=/path/to/virtualenvs/directory

これは、資格情報などの秘密の設定にも有効です。

export POETRY_HTTP_BASIC_MY_REPOSITORY_PASSWORD=secret

デフォルトディレクトリ #

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

設定ディレクトリ #

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

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

データディレクトリ #

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

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

キャッシュディレクトリ #

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

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

利用可能な設定 #

`cache-dir` #

型: string

環境変数: POETRY_CACHE_DIR

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

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

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

`experimental.system-git-client` #

型: boolean

デフォルト: false

環境変数: POETRY_EXPERIMENTAL_SYSTEM_GIT_CLIENT

1.2.0で導入されました

git関連のタスクにシステムのgitクライアントバックエンドを使用します。

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

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

`installer.max-workers` #

型: int

デフォルト: number_of_cores + 4

環境変数: POETRY_INSTALLER_MAX_WORKERS

1.2.0で導入されました

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

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

注意

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

`installer.modern-installation` #

型: boolean

デフォルト: true

環境変数: POETRY_INSTALLER_MODERN_INSTALLATION

1.4.0 で導入

パッケージインストールのためのよりモダンで高速なメソッドを使用します。

もしこれが問題を引き起こす場合、false に設定して無効にし、発生した問題を issue tracker に報告してください。

`installer.no-binary` #

型: string | boolean

デフォルト: false

環境変数: POETRY_INSTALLER_NO_BINARY

1.2.0で導入されました

この設定を使用すると、ユーザーはすべてのパッケージまたは特定のパッケージのパッケージ配布形式ポリシーを設定できます。

設定	説明
`:all:` または `true`	すべてのパッケージでバイナリ配布を許可しません。
`:none:` または `false`	すべてのパッケージでバイナリ配布を許可します。
`package[,package,..]`	指定されたパッケージのみ、バイナリ配布を許可しません。

注意

ここに記載されているすべての設定と同様に、これはユーザー固有の設定です。つまり、ロックファイルが生成されたり、依存関係が解決されたりする際には考慮されません。これは、Poetry によって管理される環境にインストールする依存関係の配布を選択する場合にのみ適用されます。

注意

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

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

注意

CI またはコンテナ環境では、環境変数を使用してこれを設定すると便利な場合があります。

export POETRY_INSTALLER_NO_BINARY=:all:

警告

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

`installer.parallel` #

型: boolean

デフォルト: true

環境変数: POETRY_INSTALLER_PARALLEL

1.1.4 で導入

新しい (>=1.1.0) インストーラーを使用する際、並列実行を使用します。

`solver.lazy-wheel` #

型: boolean

デフォルト: true

環境変数: POETRY_SOLVER_LAZY_WHEEL

1.8.0 で導入

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

`virtualenvs.create` #

型: boolean

デフォルト: true

環境変数: POETRY_VIRTUALENVS_CREATE

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

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

注意

Poetry がアクティブ化された仮想環境内で実行されていることを検出した場合、virtualenvs.create に設定された値に関係なく、新しい仮想環境を作成することはありません。

注意

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

そのため、常に仮想環境を作成することをお勧めします。これは、追加の Python パッケージが含まれる可能性のある Docker コンテナでも同様です。

`virtualenvs.in-project` #

型: boolean

デフォルト: None

環境変数: POETRY_VIRTUALENVS_IN_PROJECT

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

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

true に設定すると、仮想環境はプロジェクトのルートディレクトリ内の .venv という名前のフォルダーに作成され、そこに配置されると想定されます。

注意

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

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

現在のプロジェクトの仮想環境 (存在する場合) が保存されている場所は、コマンド poetry env info --path で確認できます。

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

`virtualenvs.options.always-copy` #

型: boolean

デフォルト: false

環境変数: POETRY_VIRTUALENVS_OPTIONS_ALWAYS_COPY

1.2.0で導入されました

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

`virtualenvs.options.no-pip` #

型: boolean

デフォルト: false

環境変数: POETRY_VIRTUALENVS_OPTIONS_NO_PIP

1.2.0で導入されました

true に設定すると、仮想環境の作成時に --no-pip パラメーターが virtualenv に渡されます。つまり、新しい仮想環境が作成されると、pip はその環境にインストールされません。

注意

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

追加のパッケージがない仮想環境が必要な場合は、これを no-setuptools とともに true に設定しても安全です。これは、本番環境に望ましいことです。

`virtualenvs.options.no-setuptools` #

型: boolean

デフォルト: false

環境変数: POETRY_VIRTUALENVS_OPTIONS_NO_SETUPTOOLS

1.2.0で導入されました

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

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

警告

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

`virtualenvs.options.system-site-packages` #

型: boolean

デフォルト: false

環境変数: POETRY_VIRTUALENVS_OPTIONS_SYSTEM_SITE_PACKAGES

仮想環境にシステムの site-packages ディレクトリへのアクセスを許可します。仮想環境の作成時に適用されます。

`virtualenvs.path` #

型: string

デフォルト: {cache-dir}/virtualenvs

環境変数: POETRY_VIRTUALENVS_PATH

仮想環境が作成されるディレクトリ。

注意

この設定は、グローバルな仮想環境の保存パスを制御します。ローカルレベルでは役に立たない可能性が非常に高いです。プロジェクトのルートに仮想環境を保存するには、virtualenvs.in-project を参照してください。

`virtualenvs.prefer-active-python` (実験的) #

型: boolean

デフォルト: false

環境変数: POETRY_VIRTUALENVS_PREFER_ACTIVE_PYTHON

1.2.0で導入されました

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

`virtualenvs.prompt` #

型: string

デフォルト: {project_name}-py{python_version}

環境変数: POETRY_VIRTUALENVS_PROMPT

1.2.0で導入されました

仮想環境がアクティブ化されたときに表示されるプロンプトを定義する書式設定文字列。project_name と python_version の変数を使用して書式設定できます。

`repositories.<name>.url` #

型: string

環境変数: POETRY_REPOSITORIES_<NAME>_URL

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

詳細については、公開可能なリポジトリを参照してください。

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

型: string

環境変数: POETRY_HTTP_BASIC_<NAME>_USERNAME, POETRY_HTTP_BASIC_<NAME>_PASSWORD

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

`pypi-token.<name>`: #

型: string

環境変数: POETRY_PYPI_TOKEN_<NAME>

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

`certificates.<name>.cert`: #

型: string | boolean

環境変数: POETRY_CERTIFICATES_<NAME>_CERT

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

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

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

型: string

環境変数: POETRY_CERTIFICATES_<NAME>_CLIENT_CERT

リポジトリ <name> のクライアント証明書を設定します。詳細については、リポジトリ - 認証情報の設定 - カスタム認証局を参照してください。

`keyring.enabled`: #

型: boolean

デフォルト: true

環境変数: POETRY_KEYRING_ENABLED

認証情報を保存するためにシステムキーリングを有効にします。詳細については、リポジトリ - 認証情報の設定を参照してください。

設定

設定 #

ローカル設定 #

現在の設定を一覧表示する #

単一の設定を表示する #

設定の追加または更新 #

特定の設定を削除する #

環境変数の使用 #

デフォルトディレクトリ #

設定ディレクトリ #

データディレクトリ #

キャッシュディレクトリ #

利用可能な設定 #

cache-dir #

experimental.system-git-client #

installer.max-workers #

installer.modern-installation #

installer.no-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 (実験的) #

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.modern-installation` #

`installer.no-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` (実験的) #

`virtualenvs.prompt` #

`repositories.<name>.url` #

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

`pypi-token.<name>`: #

`certificates.<name>.cert`: #

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

`keyring.enabled`: #