Skip to content

Working with Virtual Environments#

pdm initコマンドを実行すると、PDMはプロジェクト内でask for the Python interpreter to useします。これは、依存関係をインストールしてタスクを実行するためのベースインタプリタです。

PEP 582と比較すると、仮想環境はより成熟していると考えられ、IDEだけでなくPythonエコシステムでもよりよくサポートされています。したがって、特に設定されていない場合は、virtualenvがデフォルトモードになります。

プロジェクトインタプリタ(.pdm-pythonに保存され、pdm infoで確認できるインタプリタ)がvirtualenvからのものである場合、仮想環境が使用されます。

Virtualenv auto-creation#

デフォルトでは、PDMは他のパッケージマネージャと同様にvirtualenvレイアウトの使用を優先します。Pythonインタプリタがまだ決定されていない新しいPDM管理プロジェクトでpdm installを初めて実行すると、PDMは<project_root>/.venvにvirtualenvを作成し、そこに依存関係をインストールします。pdm initの対話型セッションでは、PDMはvirtualenvの作成も要求します。

PDMがvirtualenvの作成に使用するバックエンドを選択できます。現在、次の3つのバックエンドがサポートされています。:

これはpdm config venv.backend [virtualenv|venv|conda]で変更できます。

Added in version 2.13.0

さらに、python.use_venvconfigがtrueに設定されている場合、PDMはpdm useを使用してPythonインタプリタを切り替えるときに、常にvirtualenvの作成を試みます。

Create a virtualenv yourself#

任意のPythonバージョンで複数のvirtualenvを作成できます。

1
2
3
4
5
6
# Create a virtualenv based on 3.8 interpreter
pdm venv create 3.8
# Assign a different name other than the version string
pdm venv create --name for-test 3.8
# Use venv as the backend to create, support 3 backends: virtualenv(default), venv, conda
pdm venv create --with venv 3.9

The location of virtualenvs#

If no --name is given, PDM will create the venv in <project_root>/.venv. Otherwise, virtualenvs go to the location specified by the venv.location configuration. They are named as <project_name>-<path_hash>-<name_or_python_version> to avoid name collision. You can disable the in-project virtualenv creation by pdm config venv.in_project false. And all virtualenvs will be created under venv.location.

--nameが指定されていない場合、PDMは<project_root>/.venvにvenvを作成します。それ以外の場合、virtualenvはvenv.location設定で指定された場所に移動します。名前の衝突を避けるために、それらは<project_name>-<path_hash>-<name_or_python_version>として名前が付けられます。pdm config venv.in_project falseを使用して、プロジェクト内のvirtualenvの作成を無効にできます。すべてのvirtualenvはvenv.locationの下に作成されます。

Reuse the virtualenv you created elsewhere#

pdm useを使用して、前の手順で作成したvirtualenvを使用するようにPDMに指示できます。

1
pdm use -f /path/to/venv

Virtualenv auto-detection#

インタプリタがプロジェクト構成に保存されていない場合、またはPDM_IGNORE_SAVED_PYTHONenv varが設定されている場合、PDMは使用可能なvirtualenvの検出を試みます。:

  • プロジェクトルートのvenv、env、.venvディレクトリ
  • PDM_IGNORE_ACTIVE_VENVが設定されていない限り、現在アクティブ化されているvirtualenv

List all virtualenvs created with this project#

1
2
3
4
5
6
$ pdm venv list
Virtualenvs created with this project:

-  3.8.6: C:\Users\Frost Ming\AppData\Local\pdm\pdm\venvs\test-project-8Sgn_62n-3.8.6
-  for-test: C:\Users\Frost Ming\AppData\Local\pdm\pdm\venvs\test-project-8Sgn_62n-for-test
-  3.9.1: C:\Users\Frost Ming\AppData\Local\pdm\pdm\venvs\test-project-8Sgn_62n-3.9.1

Show the path or python interpreter of a virtualenv#

1
2
pdm venv --path for-test
pdm venv --python for-test

Remove a virtualenv#

1
2
3
4
$ pdm venv remove for-test
Virtualenvs created with this project:
Will remove: C:\Users\Frost Ming\AppData\Local\pdm\pdm\venvs\test-project-8Sgn_62n-for-test, continue? [y/N]:y
Removed C:\Users\Frost Ming\AppData\Local\pdm\pdm\venvs\test-project-8Sgn_62n-for-test

Activate a virtualenv#

pipenvやpoetryのようにサブシェルを生成する代わりに、pdm venvはシェルを作成せず、コンソールにactivateコマンドを出力します。このようにして、現在のシェルを離れることはありません。出力をevalに渡して、virtualenvをアクティブにすることができます。:

1
2
$ eval $(pdm venv activate for-test)
(test-project-for-test) $  # Virtualenv entered

1
$ eval (pdm venv activate for-test)

1
PS1> Invoke-Expression (pdm venv activate for-test)

また、プロジェクトインタプリタがvenv Pythonの場合は、activateの後のname引数を省略できます。

Note

venv activateは、プロジェクトで使用されるPythonインタプリタを切り替えません。virtualenvパスを環境変数に注入することによってシェルを変更するだけです。前述の目的のためには、pdm useコマンドを使用してください。

CLIの使用方法の詳細については、pdm venvのドキュメントを参照してください。

Looking for pdm shell?

PDMにはshellコマンドが用意されていません。これは、多くの高度なシェル機能がサブシェルで完全に動作しない可能性があり、すべてのコーナーケースをサポートするためのメンテナンスの負担が発生するためです。ただし、次の方法で機能を追加することもできます。

-pdm run$SHELLを使用します。これにより、環境変数が正しく設定されたサブシェルが生成されます。サブシェルはexitまたはCtrl+Dで終了できます。 -virtualenvを有効にするシェル関数を追加します。ZSHでも動作するBASH関数の例を次に示します。

1
2
3
4
5
6
7
8
9
pdm() {
  local command=$1

  if [[ "$command" == "shell" ]]; then
      eval $(pdm venv activate)
  else
      command pdm $@
  fi
}

この関数をコピーして~/.bashrcファイルに貼り付け、シェルを再起動してください。

fishシェルでは、以下を~/fish/config.fishまたは~/.config/fish/config.fishに入れることができます。

1
2
3
4
5
6
7
8
9
  function pdm
      set cmd $argv[1]

      if test "$cmd" = "shell"
          eval (pdm venv activate)
      else
          command pdm $argv
      end
  end

これでpdm shellを実行してvirtualenvをアクティブにできます。 virtualenvは通常どおりdeactivateコマンドで非アクティブにできます。

Prompt customization#

デフォルトでは、virtualenvを有効にすると、{project_name}-{python_version}というプロンプトが表示されます。

たとえば、プロジェクト名がtest-projectの場合は、次のようになります。:

1
2
$ eval $(pdm venv activate for-test)
(test-project-3.10) $  # {project_name} == test-project and {python_version} == 3.10

フォーマットは、virtualenvの作成前に、venv.prompt構成またはPDM_VENV_PROMPT環境変数(pdm initまたはpdm venv createの前)を使用してカスタマイズできます。 使用可能な変数は次のとおりです。:

  • project_name:プロジェクトの名前
  • python_version:Pythonのバージョン(virtualenvによって使用されます)
1
2
3
$ PDM_VENV_PROMPT='{project_name}-py{python_version}' pdm venv create --name test-prompt
$ eval $(pdm venv activate test-prompt)
(test-project-py3.10) $

Run a command in a virtual environment without activating it#

1
2
3
4
5
6
# Run a script
pdm run --venv test test
# Install packages
pdm sync --venv test
# List the packages installed
pdm list --venv test

--venvフラグまたはPDM_IN_VENV環境変数をサポートするコマンドは他にもあります。CLI referenceを参照してください。この機能を使用する前に、pdm venv create --name <name>でvirtualenvを作成する必要があります。

Switch to a virtualenv as the project environment#

デフォルトでは、pdm useを使用してvenv以外のPythonを選択すると、プロジェクトはpep 582 modeに切り替えられます。また、--venvフラグを使用して、名前付きの仮想環境に切り替えることもできます。:

1
2
3
4
# Switch to a virtualenv named test
$ pdm use --venv test
# Switch to the in-project venv located at $PROJECT_ROOT/.venv
$ pdm use --venv in-project

Disable virtualenv mode#

pdm config python.use_venv falseを使用して、virtualenvの自動作成と自動検出を無効にすることができます。 venvを無効にすると、選択したインタプリタがvirtualenvからのものであっても、常にPEP 582モードが使用されます。

Including pip in your virtual environment#

デフォルトでは、PDMは仮想環境にpipを含めません。 これにより、依存関係のみが仮想環境に確実にインストールされ、分離が強化されます。

pipを一度インストールするには(たとえば、CIに任意の依存関係をインストールしたい場合)、次のコマンドを実行します。

1
2
3
4
5
# Install pip in the virtual environment
pdm run python -m ensurepip
# Install arbitrary dependencies
# These dependencies are not checked for conflicts against lockfile dependencies!
pdm run python -m pip install coverage

または、--with-pipで仮想環境を作成することもできます。

1
pdm venv create --with-pip 3.9

See the ensurepip docs for more details on ensurepip.

ensurepipの詳細については、ensurepip docsを参照してください。

仮想環境にpipを含めるようにPDMを永続的に設定する場合は、venv.with_pip設定を使用できます。