diff --git a/dev/dev/fixtures/index.html b/dev/dev/fixtures/index.html
index 8243e77aa7..93bc703f15 100644
--- a/dev/dev/fixtures/index.html
+++ b/dev/dev/fixtures/index.html
@@ -742,8 +742,8 @@
 </li>
       
         <li class="md-nav__item">
-  <a href="#pdm.pytest.LocalFileAdapter" class="md-nav__link">
-    LocalFileAdapter
+  <a href="#pdm.pytest.LocalIndexTransport" class="md-nav__link">
+    LocalIndexTransport
   </a>
   
 </li>
@@ -1055,8 +1055,8 @@
 </li>
       
         <li class="md-nav__item">
-  <a href="#pdm.pytest.LocalFileAdapter" class="md-nav__link">
-    LocalFileAdapter
+  <a href="#pdm.pytest.LocalIndexTransport" class="md-nav__link">
+    LocalIndexTransport
   </a>
   
 </li>
@@ -1327,7 +1327,7 @@ <h2 id="pdm.pytest.IndexMap" class="doc doc-heading">
 
 
 <h2 id="pdm.pytest.IndexOverrides" class="doc doc-heading">
-<code class="highlight language-python"><span class="n">IndexOverrides</span> <span class="o">=</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span></code>
+<code class="highlight language-python"><span class="n">IndexOverrides</span> <span class="o">=</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">]</span></code>
   
   <span class="doc doc-labels">
       <small class="doc doc-label doc-label-module-attribute"><code>module-attribute</code></small>
@@ -1407,19 +1407,19 @@ <h2 id="pdm.pytest.Distribution" class="doc doc-heading">
 
 
 
-<h2 id="pdm.pytest.LocalFileAdapter" class="doc doc-heading">
-        <code>LocalFileAdapter</code>
+<h2 id="pdm.pytest.LocalIndexTransport" class="doc doc-heading">
+        <code>LocalIndexTransport</code>
 
 
-<a href="#pdm.pytest.LocalFileAdapter" class="headerlink" title="Permanent link">#</a></h2>
+<a href="#pdm.pytest.LocalIndexTransport" class="headerlink" title="Permanent link">#</a></h2>
 
 
   <div class="doc doc-contents ">
       <p class="doc doc-class-bases">
-        Bases: <code>requests.<span title="requests.adapters">adapters</span>.<span title="requests.adapters.BaseAdapter">BaseAdapter</span></code></p>
+        Bases: <code>httpx.<span title="httpx.BaseTransport">BaseTransport</span></code></p>
 
   
-      <p>A local file adapter for request.</p>
+      <p>A local file transport for HTTPX.</p>
 <p>Allows to mock some HTTP requests with some local files</p>
 
 
@@ -2062,7 +2062,7 @@ <h2 id="pdm.pytest.project" class="doc doc-heading">
 
 
 <h2 id="pdm.pytest.project_no_init" class="doc doc-heading">
-<code class="highlight language-python"><span class="n">project_no_init</span><span class="p">(</span><span class="n">tmp_path</span><span class="p">,</span> <span class="n">mocker</span><span class="p">,</span> <span class="n">core</span><span class="p">,</span> <span class="n">pdm_session</span><span class="p">,</span> <span class="n">monkeypatch</span><span class="p">,</span> <span class="n">build_env</span><span class="p">)</span></code>
+<code class="highlight language-python"><span class="n">project_no_init</span><span class="p">(</span><span class="n">tmp_path</span><span class="p">,</span> <span class="n">mocker</span><span class="p">,</span> <span class="n">core</span><span class="p">,</span> <span class="n">build_test_session</span><span class="p">,</span> <span class="n">monkeypatch</span><span class="p">,</span> <span class="n">build_env</span><span class="p">)</span></code>
 
 <a href="#pdm.pytest.project_no_init" class="headerlink" title="Permanent link">#</a></h2>
 
diff --git a/dev/objects.inv b/dev/objects.inv
index 25e9fdc1c3..3d74e06d86 100644
Binary files a/dev/objects.inv and b/dev/objects.inv differ
diff --git a/dev/reference/api/index.html b/dev/reference/api/index.html
index 0296440b7b..0e70d6c0c8 100644
--- a/dev/reference/api/index.html
+++ b/dev/reference/api/index.html
@@ -658,6 +658,13 @@
     <nav class="md-nav" aria-label="Core">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#pdm.core.Core.state" class="md-nav__link">
+    state
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#pdm.core.Core.add_config" class="md-nav__link">
     add_config()
@@ -691,6 +698,13 @@
     main()
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#pdm.core.Core.push_state" class="md-nav__link">
+    push_state()
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -1082,6 +1096,13 @@
     <nav class="md-nav" aria-label="Core">
       <ul class="md-nav__list">
         
+          <li class="md-nav__item">
+  <a href="#pdm.core.Core.state" class="md-nav__link">
+    state
+  </a>
+  
+</li>
+        
           <li class="md-nav__item">
   <a href="#pdm.core.Core.add_config" class="md-nav__link">
     add_config()
@@ -1115,6 +1136,13 @@
     main()
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#pdm.core.Core.push_state" class="md-nav__link">
+    push_state()
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -1386,6 +1414,27 @@ <h2 id="pdm.core.Core" class="doc doc-heading">
 
 
 
+<div class="doc doc-object doc-attribute">
+
+
+
+<h3 id="pdm.core.Core.state" class="doc doc-heading">
+<code class="highlight language-python"><span class="n">state</span><span class="p">:</span> <span class="n">State</span></code>
+  
+  <span class="doc doc-labels">
+      <small class="doc doc-label doc-label-property"><code>property</code></small>
+  </span>
+
+<a href="#pdm.core.Core.state" class="headerlink" title="Permanent link">#</a></h3>
+
+
+  <div class="doc doc-contents ">
+  
+      <p>Get the current state object.</p>
+  </div>
+
+</div>
+
 
 
 <div class="doc doc-object doc-function">
@@ -1590,6 +1639,58 @@ <h3 id="pdm.core.Core.main" class="doc doc-heading">
 
 
 
+<h3 id="pdm.core.Core.push_state" class="doc doc-heading">
+<code class="highlight language-python"><span class="n">push_state</span><span class="p">(</span><span class="n">__empty</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span></code>
+
+<a href="#pdm.core.Core.push_state" class="headerlink" title="Permanent link">#</a></h3>
+
+
+  <div class="doc doc-contents ">
+  
+      <p>Push a new state object to the stack.</p>
+
+  <p><strong>Parameters:</strong></p>
+  <table>
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th>Type</th>
+        <th>Description</th>
+        <th>Default</th>
+      </tr>
+    </thead>
+    <tbody>
+        <tr>
+          <td><code>__empty</code></td>
+          <td>
+                <code>bool</code>
+          </td>
+          <td><p>Whether to make an empty state.</p></td>
+          <td>
+                <code>False</code>
+          </td>
+        </tr>
+        <tr>
+          <td><code>**kwargs</code></td>
+          <td>
+                <code><span title="typing.Any">Any</span></code>
+          </td>
+          <td><p>The new attributes to set to the state object.</p></td>
+          <td>
+                <code>{}</code>
+          </td>
+        </tr>
+    </tbody>
+  </table>
+
+  </div>
+
+</div>
+
+<div class="doc doc-object doc-function">
+
+
+
 <h3 id="pdm.core.Core.register_command" class="doc doc-heading">
 <code class="highlight language-python"><span class="n">register_command</span><span class="p">(</span><span class="n">command</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span></code>
 
@@ -1738,8 +1839,8 @@ <h3 id="pdm.project.core.Project.config" class="doc doc-heading">
 <code class="highlight language-python"><span class="n">config</span><span class="p">:</span> <span class="n">Mapping</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">]</span></code>
   
   <span class="doc doc-labels">
-      <small class="doc doc-label doc-label-property"><code>property</code></small>
       <small class="doc doc-label doc-label-cached"><code>cached</code></small>
+      <small class="doc doc-label doc-label-property"><code>property</code></small>
   </span>
 
 <a href="#pdm.project.core.Project.config" class="headerlink" title="Permanent link">#</a></h3>
@@ -1781,8 +1882,8 @@ <h3 id="pdm.project.core.Project.project_config" class="doc doc-heading">
 <code class="highlight language-python"><span class="n">project_config</span><span class="p">:</span> <span class="n">Config</span></code>
   
   <span class="doc doc-labels">
-      <small class="doc doc-label doc-label-property"><code>property</code></small>
       <small class="doc doc-label doc-label-cached"><code>cached</code></small>
+      <small class="doc doc-label doc-label-property"><code>property</code></small>
   </span>
 
 <a href="#pdm.project.core.Project.project_config" class="headerlink" title="Permanent link">#</a></h3>
diff --git a/dev/reference/cli/index.html b/dev/reference/cli/index.html
index feeef68bd9..a5e9cb5f23 100644
--- a/dev/reference/cli/index.html
+++ b/dev/reference/cli/index.html
@@ -1487,6 +1487,7 @@ <h1 id="cli-reference">CLI Reference<a class="headerlink" href="#cli-reference"
 <li><code>-c</code>, <code>--config</code>: Specify another config file path [env var: <code>PDM_CONFIG_FILE</code>] </li>
 <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li>
 <li><code>-q</code>, <code>--quiet</code>: Suppress output</li>
+<li><code>--no-cache</code>: Disable the cache for the current command. [env var: <code>PDM_NO_CACHE</code>]</li>
 <li><code>-I</code>, <code>--ignore-python</code>: Ignore the Python path saved in<code>.pdm-python</code>. [env var: <code>PDM_IGNORE_SAVED_PYTHON</code>]</li>
 <li><code>--pep582</code> <code>SHELL</code>: Print the command line to be eval'd by the shell</li>
 </ul>
@@ -1841,6 +1842,7 @@ <h3 id="lock">lock<a class="headerlink" href="#lock" title="Permanent link">#</a
 <li><code>--check</code>: Check if the lock file is up to date and quit</li>
 <li><code>--update-reuse</code>: Reuse pinned versions already present in lock file if possible (default: <code>all</code>)</li>
 <li><code>--update-reuse-installed</code>: Reuse installed packages if possible</li>
+<li><code>--exclude-newer</code>: Exclude packages newer than the given UTC date in format <code>YYYY-MM-DD[THH:MM:SSZ]</code></li>
 </ul>
 <p>Lock Strategy:</p>
 <ul>
diff --git a/dev/search/search_index.json b/dev/search/search_index.json
index 50aeff8eac..42588bc0c5 100644
--- a/dev/search/search_index.json
+++ b/dev/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":""},{"location":"#introduction","title":"Introduction","text":"<p>PDM, as described, is a modern Python package and dependency manager supporting the latest PEP standards. But it is more than a package manager. It boosts your development workflow in various aspects.</p>"},{"location":"#feature-highlights","title":"Feature highlights","text":"<ul> <li>Simple and fast dependency resolver, mainly for large binary distributions.</li> <li>A PEP 517 build backend.</li> <li>PEP 621 project metadata.</li> <li>Flexible and powerful plug-in system.</li> <li>Versatile user scripts.</li> <li>Opt-in centralized installation cache like pnpm.</li> </ul>"},{"location":"#installation","title":"Installation","text":"<p>PDM requires Python 3.8+ to be installed. It works on multiple platforms including Windows, Linux and macOS.</p> <p>Note</p> <p>You can still have your project working on lower Python versions, read how to do it here.</p>"},{"location":"#recommended-installation-method","title":"Recommended installation method","text":"<p>PDM requires python version 3.8 or higher.</p> <p>Like Pip, PDM provides an installation script that will install PDM into an isolated environment.</p> Linux/MacWindows <pre><code>curl -sSL https://pdm-project.org/install-pdm.py | python3 -\n</code></pre> <pre><code>(Invoke-WebRequest -Uri https://pdm-project.org/install-pdm.py -UseBasicParsing).Content | py -\n</code></pre> <p>For security reasons, you should verify the checksum of <code>install-pdm.py</code>. It can be downloaded from install-pdm.py.sha256.</p> <p>For example, on Linux/Mac:</p> <pre><code>curl -sSLO https://pdm-project.org/install-pdm.py\ncurl -sSL https://pdm-project.org/install-pdm.py.sha256 | shasum -a 256 -c -\n# Run the installer\npython3 install-pdm.py [options]\n</code></pre> <p>The installer will install PDM into the user site and the location depends on the system:</p> <ul> <li><code>$HOME/.local/bin</code> for Unix</li> <li><code>$HOME/Library/Python/&lt;version&gt;/bin</code> for MacOS</li> <li><code>%APPDATA%\\Python\\Scripts</code> on Windows</li> </ul> <p>You can pass additional options to the script to control how PDM is installed:</p> <pre><code>usage: install-pdm.py [-h] [-v VERSION] [--prerelease] [--remove] [-p PATH] [-d DEP]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v VERSION, --version VERSION | envvar: PDM_VERSION\n                        Specify the version to be installed, or HEAD to install from the main branch\n  --prerelease | envvar: PDM_PRERELEASE    Allow prereleases to be installed\n  --remove | envvar: PDM_REMOVE            Remove the PDM installation\n  -p PATH, --path PATH | envvar: PDM_HOME  Specify the location to install PDM\n  -d DEP, --dep DEP | envvar: PDM_DEPS     Specify additional dependencies, can be given multiple times\n</code></pre> <p>You can either pass the options after the script or set the env var value.</p>"},{"location":"#other-installation-methods","title":"Other installation methods","text":"HomebrewScooppipxpipasdfinside project <pre><code>brew install pdm\n</code></pre> <pre><code>scoop bucket add frostming https://github.com/frostming/scoop-frostming.git\nscoop install pdm\n</code></pre> <pre><code>pipx install pdm\n</code></pre> <p>Install the head version of GitHub repository. Make sure you have installed Git LFS on your system.</p> <pre><code>pipx install git+https://github.com/pdm-project/pdm.git@main#egg=pdm\n</code></pre> <p>To install PDM with all features:</p> <pre><code>pipx install pdm[all]\n</code></pre> <p>See also: https://pypa.github.io/pipx/</p> <pre><code>pip install --user pdm\n</code></pre> <p>Assuming you have asdf installed. <pre><code>asdf plugin add pdm\nasdf local pdm latest\nasdf install pdm\n</code></pre></p> <p>By copying the Pyprojectx wrapper scripts to a project, you can install PDM as (npm-style) dev dependency inside that project. This allows different projects/branches to use different PDM versions.</p> <p>To initialize a new or existing project, cd into the project folder and:</p> Linux/MacWindows <pre><code>curl -LO https://github.com/pyprojectx/pyprojectx/releases/latest/download/wrappers.zip &amp;&amp; unzip wrappers.zip &amp;&amp; rm -f wrappers.zip\n./pw --add pdm\n</code></pre> <pre><code>Invoke-WebRequest https://github.com/pyprojectx/pyprojectx/releases/latest/download/wrappers.zip -OutFile wrappers.zip; Expand-Archive -Path wrappers.zip -DestinationPath .; Remove-Item -Path wrappers.zip\n.\\pw --add pdm\n</code></pre> <p>When installing pdm with this method, you need to run all <code>pdm</code> commands through the <code>pw</code> wrapper:</p> Linux/Mac/Windows <pre><code>./pw pdm install\n</code></pre>"},{"location":"#update-the-pdm-version","title":"Update the PDM version","text":"<pre><code>pdm self update\n</code></pre>"},{"location":"#packaging-status","title":"Packaging Status","text":""},{"location":"#shell-completion","title":"Shell Completion","text":"<p>PDM supports generating completion scripts for Bash, Zsh, Fish or Powershell. Here are some common locations for each shell:</p> BashZshFishPowershell <pre><code>pdm completion bash &gt; /etc/bash_completion.d/pdm.bash-completion\n</code></pre> <pre><code># Make sure ~/.zfunc is added to fpath, before compinit.\npdm completion zsh &gt; ~/.zfunc/_pdm\n</code></pre> <p>Oh-My-Zsh:</p> <pre><code>mkdir $ZSH_CUSTOM/plugins/pdm\npdm completion zsh &gt; $ZSH_CUSTOM/plugins/pdm/_pdm\n</code></pre> <p>Then make sure pdm plugin is enabled in ~/.zshrc</p> <pre><code>pdm completion fish &gt; ~/.config/fish/completions/pdm.fish\n</code></pre> <pre><code># Create a directory to store completion scripts\nmkdir $PROFILE\\..\\Completions\necho @'\nGet-ChildItem \"$PROFILE\\..\\Completions\\\" | ForEach-Object {\n    . $_.FullName\n}\n'@ | Out-File -Append -Encoding utf8 $PROFILE\n# Generate script\nSet-ExecutionPolicy Unrestricted -Scope CurrentUser\npdm completion powershell | Out-File -Encoding utf8 $PROFILE\\..\\Completions\\pdm_completion.ps1\n</code></pre>"},{"location":"#virtualenv-and-pep-582","title":"Virtualenv and PEP 582","text":"<p>PDM offers experimental support for PEP 582 as an opt-in feature, in addition to virtualenv management. Although the Python Steering Council has rejected PEP 582, you can still test it out using PDM.</p> <p>To learn more about the two modes, refer to the relevant chapters on Working with virtualenv and Working with PEP 582.</p>"},{"location":"#pdm-eco-system","title":"PDM Eco-system","text":"<p>Awesome PDM is a curated list of awesome PDM plugins and resources.</p>"},{"location":"#sponsors","title":"Sponsors","text":""},{"location":"dev/benchmark/","title":"Benchmark","text":"<p>This page has been removed, please visit https://lincolnloop.github.io/python-package-manager-shootout/ for a detailed benchmark report.</p>"},{"location":"dev/changelog/","title":"Changelog","text":"<p>Attention</p> <p>Major and minor releases also include changes listed within prior beta releases.</p>"},{"location":"dev/changelog/#release-v2124-2024-02-26","title":"Release v2.12.4 (2024-02-26)","text":""},{"location":"dev/changelog/#features-improvements","title":"Features &amp; Improvements","text":"<ul> <li>Use env PDM_NO_EDITABLE as the default value for --no-editable option. #2613</li> </ul>"},{"location":"dev/changelog/#bug-fixes","title":"Bug Fixes","text":"<ul> <li>Reset project.environment when importing from setup.py, to fix resolution error. #2608</li> <li>Do not fetch package hashes when <code>--frozen-lockfile</code> is passed. #2630</li> <li>Make sure non-venv interpreters are used by venv creator. #2631</li> <li>Don't cause a hard failure if the local directory doesn't exist. #2650</li> </ul>"},{"location":"dev/changelog/#documentation","title":"Documentation","text":"<ul> <li>Fix the default value for negative CLI flags. #2642</li> <li>Auto-gen configuration reference documentation. #2645</li> </ul>"},{"location":"dev/changelog/#release-v2123-2024-02-01","title":"Release v2.12.3 (2024-02-01)","text":""},{"location":"dev/changelog/#bug-fixes_1","title":"Bug Fixes","text":"<ul> <li>fix the package-type fixer won't update toml properly for \"Nested Section Ordering Issue in TOML\". #2578</li> <li>Unable to force override a package if the package is required with extras. #2586</li> <li>Failed to clone template repository if the URL contains the rev part. #2597</li> <li>Handle legacy specifiers when converting from poetry project. #2599</li> </ul>"},{"location":"dev/changelog/#documentation_1","title":"Documentation","text":"<ul> <li>Fix typo in template docs #2588</li> </ul>"},{"location":"dev/changelog/#release-v2122-2024-01-21","title":"Release v2.12.2 (2024-01-21)","text":""},{"location":"dev/changelog/#bug-fixes_2","title":"Bug Fixes","text":"<ul> <li>Fix the auto fixer for package-type. #2564</li> <li>Fix the wrong installation destination for header files when installing build requirements. #2573</li> <li>Install header files into package namespace under <code>include</code> directory. #2574</li> </ul>"},{"location":"dev/changelog/#release-v2121-2024-01-17","title":"Release v2.12.1 (2024-01-17)","text":""},{"location":"dev/changelog/#bug-fixes_3","title":"Bug Fixes","text":"<ul> <li>Hotfix: missing <code>identifier</code> attribute for package type fixer. #2564</li> </ul>"},{"location":"dev/changelog/#release-v2120-2024-01-17","title":"Release v2.12.0 (2024-01-17)","text":""},{"location":"dev/changelog/#features-improvements_1","title":"Features &amp; Improvements","text":"<ul> <li>Allow excluding packages from the lockfile via <code>tool.pdm.resolution.excludes</code> setting, the dependencies will also be skipped. #1316</li> <li>Rename <code>--no-lock</code> option to <code>--frozen-lockfile</code>. #2496</li> <li>Add <code>--no-hashes</code> as the recommended option name in favor of <code>--without-hashes</code> for <code>pdm export</code> command. #2497</li> <li>Add <code>--no-markers</code> to <code>export</code> command to exclude markers from the output. #2497</li> <li>Allow initializing a project without extra project files, with a new builtin template \"minimal\". Run it with <code>pdm init minimal</code>. #2543</li> <li>Change the warning category emitted by <code>deprecated_warning()</code> to <code>PDMDeprecationWarning</code>. #2547</li> <li>Prereleases will be allowed if a prerelease version is pinned in the lockfile. This can be disabled by passing <code>--stable</code> option. #2552</li> <li>Change <code>tracked_names</code> argument to keyword-only. Move <code>allow_prereleases</code> setting to <code>tool.pdm.resolution</code> table. #2552</li> <li>Rename the <code>preferred_pins</code> argument of provider classes to <code>locked_candidates</code>, and deprecate the old name. #2552</li> <li>Rename the <code>package-type</code> field under <code>tool.pdm</code> settings table to <code>distribution</code> to make it more clear. #2564</li> </ul>"},{"location":"dev/changelog/#bug-fixes_4","title":"Bug Fixes","text":"<ul> <li><code>tool.pdm.resolution</code> settings won't be honored when installing dependencies into the build environment. #1316</li> <li>Fixed pdm list output containing full license text in some cases #2538</li> <li>Fix the environment variable substitution for <code>cmd</code> scripts. #2542</li> <li>Allow normal extension modules in wheel tags when the python is debug build. #2548</li> <li>Don't use pypi.org when pypi.url is set. #2560</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations","title":"Removals and Deprecations","text":"<ul> <li>Remove deprecated methods from <code>Project</code>. Remove deprecated helper functions from <code>actions.py</code>. #2547</li> </ul>"},{"location":"dev/changelog/#release-v2112-2024-01-02","title":"Release v2.11.2 (2024-01-02)","text":""},{"location":"dev/changelog/#bug-fixes_5","title":"Bug Fixes","text":"<ul> <li>Fix a KeyError raised when resolving a URL dependency without package name given. #2488</li> <li><code>pdm update --update-eager</code> can hit InconsistentCandidate error when dependency is included both through default dependencies and extra. #2495</li> <li><code>pdm install</code> should not warn when overwriting its own symlinks on <code>install</code>/<code>update</code>. #2502</li> <li>Fix a bug that candidates without local version are rejected when the local version is pinned. #2507</li> </ul>"},{"location":"dev/changelog/#documentation_2","title":"Documentation","text":"<ul> <li>Add maturin as a compatible build backend in the docs. #2510</li> </ul>"},{"location":"dev/changelog/#release-v2111-2023-12-14","title":"Release v2.11.1 (2023-12-14)","text":""},{"location":"dev/changelog/#bug-fixes_6","title":"Bug Fixes","text":"<ul> <li>Update candidate names before resolving markers, to fix a KeyError when the requirement is not named. #2488</li> <li>Fix a KeyError when resolving packages that have parents that are no longer needed. #2489</li> </ul>"},{"location":"dev/changelog/#release-v2110-2023-12-14","title":"Release v2.11.0 (2023-12-14)","text":""},{"location":"dev/changelog/#features-improvements_2","title":"Features &amp; Improvements","text":"<ul> <li>Officially drop the support for Python 3.7.</li> <li>Allow exporting current project as editable dependency with <code>pdm export</code>. #1910</li> <li>Improve the lockfile compatibility checking by using 3-digit version numbers. This can distinguish forward-compatibility and backward-compatibility. #2164</li> <li>Add <code>--skip-existing</code> to <code>pdm publish</code> to ignore the uploading error if the package already exists. #2362</li> <li>Use <code>==major.minor.*</code> as default requires python for application projects. #2382</li> <li>We now use the <code>package-type</code> field in the <code>tool.pdm</code> table to differentiate between library and application projects. #2394</li> <li>Add support for {pdm} placeholder in script definitions to call the same PDM entrypoint #2408</li> <li>When exporting requirements, record the environment markers from all parents for each requirement. This allows the exported requirements to work on different platforms and Python versions. #2418</li> <li><code>pdm lock</code> now supports <code>--update-reuse</code> option to keep the pinned versions in the lockfile if possible. #2419</li> <li>Introduce a new lock strategy <code>inherit_metadata</code> to inherit and merge markers from parent requirements. This is enabled by default when creating a new lockfile. #2421</li> <li>New cache methods: <code>symlink_individual</code> for creating a symlink for each individual package file and <code>hardlink</code> for creating hardlinks. #2425</li> <li>Add \"pdm sync\" pre-commit hook #2474</li> <li>New update strategy: <code>reuse-installed</code>. When this strategy is enabled, PDM will try to reuse the versions already installed in the environment, even if the package names are given in the command line following <code>add</code> or <code>update</code>. This strategy is supported by <code>add</code>, <code>update</code> and <code>lock</code> commands. #2479</li> <li>Show subcommand's help info when passing unrecognized arguments. #2480</li> <li>add <code>PDM_CACHE_DIR</code> environment variable to configure cache directory location. #2485</li> </ul>"},{"location":"dev/changelog/#bug-fixes_7","title":"Bug Fixes","text":"<ul> <li>Use the same order of Python interpreters as interactive mode in <code>pdm init -n</code>. #2436</li> <li><code>pdm init</code> now implies <code>--lib</code> if <code>--backend</code> is passed. #2437</li> <li>Fix a bug that link collection ignores package-index-binding. #2442</li> <li>Fix the wrong installation candidates for different architectures on Windows. #2464</li> <li>Fix installing PEP 561 stub-only packages with <code>install.cache_method = \"symlink\"</code>. #2466</li> <li>Fix a <code>KeyError</code> raised by <code>pdm update --unconstrained</code> when the project itself is listed as a dependency. #2483</li> </ul>"},{"location":"dev/changelog/#release-v2104-2023-11-24","title":"Release v2.10.4 (2023-11-24)","text":""},{"location":"dev/changelog/#bug-fixes_8","title":"Bug Fixes","text":"<ul> <li>Do not detect as requirements.txt if the file is a python script. #2416</li> <li>Provide information of the original line when parsing requirement fails. #2417</li> <li>Resolve <code>-r</code> requirements paths relative to the requirement file they are specified in #2422</li> <li>Updating package now overwrites the old files instead of removing before installing. #2423</li> </ul>"},{"location":"dev/changelog/#release-v2103-2023-11-16","title":"Release v2.10.3 (2023-11-16)","text":""},{"location":"dev/changelog/#bug-fixes_9","title":"Bug Fixes","text":"<ul> <li>Create virtualenv for conda base Python. #2409</li> </ul>"},{"location":"dev/changelog/#release-v2102-2023-11-16","title":"Release v2.10.2 (2023-11-16)","text":""},{"location":"dev/changelog/#features-improvements_3","title":"Features &amp; Improvements","text":"<ul> <li>Log the response text when <code>pdm publish</code> fails with HTTP error. #2400</li> </ul>"},{"location":"dev/changelog/#bug-fixes_10","title":"Bug Fixes","text":"<ul> <li>Improve the error message when a specific package can't be found in the lockfile. #2358</li> <li>prevent wrong project name (including space and illegal characters) #2360</li> <li>Fix a bug that PDM cannot detect namespace packages correctly when creating symlinks. The package's <code>__init__.py</code> contains an unusual line. #2378</li> <li>Fix template files created by <code>pdm init</code> being read-only when copied from a read-only PDM installation. #2379</li> <li>Don't reset the build backend when asking for import. #2388</li> <li>Never wrap the output of the <code>export</code> command. #2390</li> <li>Forbid global project in conda base environment, since it may remove conda-managed packages. #2409</li> </ul>"},{"location":"dev/changelog/#release-v2101-2023-11-07","title":"Release v2.10.1 (2023-11-07)","text":""},{"location":"dev/changelog/#bug-fixes_11","title":"Bug Fixes","text":"<ul> <li>Fix a bug preventing ctrl-c from interrupting program execution on 2nd invocation when using \"pdm run\" (Windows only). #2292</li> <li>Fix list index out of range when build error message is empty. #2337</li> <li>Fix find_link sources being exported as <code>--extra--index-url</code> #2342</li> <li>Fix an installation failure when install.cache = true. #2355</li> <li>Fix a resolution issue that extra dependencies are not resolved when the bare dependency has more specific version constraint. #2369</li> </ul>"},{"location":"dev/changelog/#documentation_3","title":"Documentation","text":"<ul> <li>Set up a chatbot powered by LLM on the doc page. #2365</li> </ul>"},{"location":"dev/changelog/#release-v2100-2023-10-26","title":"Release v2.10.0 (2023-10-26)","text":""},{"location":"dev/changelog/#features-improvements_4","title":"Features &amp; Improvements","text":"<ul> <li>Allow binding packages to specific sources with <code>include_packages</code> and <code>exclude_packages</code> config under <code>tool.pdm.source</code> table. #1645</li> <li>Show warnings when a package is rejected by the resolve because of uncovered <code>requires-python</code> range. And provide a way to ignore them per-package. #2304</li> <li>Add <code>-q/--quiet</code> option to suppress some warnings printed to the console. This option is mutually exclusive with <code>-v/--verbose</code>. #2304</li> <li>Introduce a new <code>--strategy/-S</code> option for <code>lock</code> command, to specify one or more strategy flags for resolving dependencies. <code>--static-urls</code> and <code>--no-cross-platform</code> are deprecated at the same time. #2310</li> <li>Add lock option to resolve direct dependencies to the minimal versions available. #2310</li> <li>Report the progress of download and unpacking when installing packages. #2328</li> </ul>"},{"location":"dev/changelog/#bug-fixes_12","title":"Bug Fixes","text":"<ul> <li>Change the venv backend clean function <code>pdm.cli.commands.venv.backend.Backend._ensure_clean</code> to empty the <code>.venv</code> folder instead of deleting it. #2282</li> <li>Fix a bug that dependency groups from Poetry 1.2+ do not migrate properly to PDM. #2285</li> <li>Fix a bug that build requirements are installed into wrong location when using <code>--venv</code> option. #2314</li> <li>Fix a bug that global repository setting results in TypeError . #2330</li> <li>Fix a credentials error when working with two indices on the same host #2333</li> </ul>"},{"location":"dev/changelog/#miscellany","title":"Miscellany","text":"<ul> <li>Officially supports python3.12 now. #2301</li> </ul>"},{"location":"dev/changelog/#release-v293-2023-09-25","title":"Release v2.9.3 (2023-09-25)","text":""},{"location":"dev/changelog/#bug-fixes_13","title":"Bug Fixes","text":"<ul> <li>Revert the changes to the behavior of installing self, introduced in #2162.   Self package won't be installed when <code>--no-default</code> is requested. #2230</li> <li>Reject the candidate if it contains invalid metadata, to avoid a crash in the process of resolution. #2261</li> </ul>"},{"location":"dev/changelog/#documentation_4","title":"Documentation","text":"<ul> <li>Clarify what <code>--no-isolated</code> does. #2071</li> </ul>"},{"location":"dev/changelog/#release-v292-2023-09-12","title":"Release v2.9.2 (2023-09-12)","text":""},{"location":"dev/changelog/#features-improvements_5","title":"Features &amp; Improvements","text":"<ul> <li>Fix an issue that <code>--no-lock</code> option doesn't work as expected. Also support <code>--no-lock</code> option for <code>add</code>, <code>remove</code> and <code>update</code> commands. #2245</li> </ul>"},{"location":"dev/changelog/#bug-fixes_14","title":"Bug Fixes","text":"<ul> <li>Use <code>findpython</code> to find pythons with the spec given by the user. #2225</li> <li>Use UTF-8 to read pyvenv.cfg. #2227</li> <li>On Windows, try looking for the <code>virtualenv</code> <code>python.exe</code> binary under <code>bin/</code>   as well as <code>Scripts/</code> and the <code>virtualenv</code>/<code>conda</code> root. #2236</li> <li>Write relocatable dependency URLs with <code>${PROJECT_ROOT}</code> variable in the lockfile. #2240</li> </ul>"},{"location":"dev/changelog/#release-v291-2023-09-03","title":"Release v2.9.1 (2023-09-03)","text":""},{"location":"dev/changelog/#features-improvements_6","title":"Features &amp; Improvements","text":"<ul> <li>Support convert setup.cfg without existing setup.py. #2222</li> </ul>"},{"location":"dev/changelog/#bug-fixes_15","title":"Bug Fixes","text":"<ul> <li><code>pdm run</code> should only find local file if the command starts with <code>./</code>. #2221</li> </ul>"},{"location":"dev/changelog/#release-v290-2023-08-31","title":"Release v2.9.0 (2023-08-31)","text":""},{"location":"dev/changelog/#features-improvements_7","title":"Features &amp; Improvements","text":"<ul> <li>Add an <code>--overwrite</code> option to <code>pdm init</code> to overwrite existing files(default False). #2163</li> <li>Support passing filter patterns as positional arguments to <code>pdm list</code> command.   Add <code>--tree</code> as an alias and preferred name of <code>--graph</code> option. #2165</li> <li>Switch to truststore by default. #2195</li> <li>Consider packages as installed if the venv includes them from the system-site-packages. #2216</li> <li>Allow <code>pdm run</code> to run a script with the relative or absolute path. #2217</li> </ul>"},{"location":"dev/changelog/#bug-fixes_16","title":"Bug Fixes","text":"<ul> <li>Fix a bug that removing dev dependency uninstalls the project as well. #2150</li> <li>Fix a bug that <code>@ file://</code> dependencies can not be updated. #2169</li> <li>Fix a bug that dependencies requested out of the range of <code>requires-python</code> cause PDM to crash. #2175</li> <li>Fix the compatibility issue with copier 8.0+. #2177</li> <li>Makes <code>comarable_version(\"1.2.3+local1\") == Version(\"1.2.3\")</code>. #2182</li> <li>Default behavior for pdm venv activate when shell detection fails. #2187</li> <li>Handle parsing errors when converting from poetry-style metadata. #2203</li> <li>Don't copy .pyc files from the template directory. #2213</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_1","title":"Removals and Deprecations","text":"<ul> <li>Remove the legacy build backend <code>pdm-pep517</code>. #2167</li> </ul>"},{"location":"dev/changelog/#release-v282-2023-07-31","title":"Release v2.8.2 (2023-07-31)","text":""},{"location":"dev/changelog/#features-improvements_8","title":"Features &amp; Improvements","text":"<ul> <li>Allow setting username and password in URL for publish command #2140</li> </ul>"},{"location":"dev/changelog/#bug-fixes_17","title":"Bug Fixes","text":"<ul> <li>Use UTF-8 encoding when writing <code>sitecustomize.py</code>. #2139</li> </ul>"},{"location":"dev/changelog/#release-v281-2023-07-26","title":"Release v2.8.1 (2023-07-26)","text":""},{"location":"dev/changelog/#features-improvements_9","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>keyring</code>, <code>copier</code>, <code>cookiecutter</code>, <code>template</code>, <code>truststore</code> dependency groups. #2109</li> <li>Ignore wheels for python versions not in range. #2113</li> <li>Read default value from env var <code>PDM_PROJECT</code> for <code>-p/--project</code> option. #2126</li> </ul>"},{"location":"dev/changelog/#bug-fixes_18","title":"Bug Fixes","text":"<ul> <li>Fix the comparison of the candidate keys in the lockfile. #2120</li> <li>Don't update <code>pyproject.toml</code> if both <code>--unconstrained</code> and <code>--dry-run</code> are passed to <code>pdm update</code>. #2125</li> <li>Overwrite the <code>build-system</code> table when importing from other package manager. #2126</li> <li>Skip sources with empty URL when merging sources. #2130</li> <li>Fix the invalid requirement converted from poetry metadata. #2133</li> </ul>"},{"location":"dev/changelog/#dependencies","title":"Dependencies","text":"<ul> <li>Update <code>unearth</code> to 0.10.0 #2113</li> </ul>"},{"location":"dev/changelog/#release-v280-2023-07-15","title":"Release v2.8.0 (2023-07-15)","text":""},{"location":"dev/changelog/#features-improvements_10","title":"Features &amp; Improvements","text":"<ul> <li>Support target python with other architectures. #2078</li> <li>Display the help information when running pdm directly. #2081</li> <li>Allow to change the python providers from the config. Support finding pythons from Rye installation location with the new findpython. #2099</li> <li>Option to save static URLs in the lockfile. By default only filenames are saved. #2101</li> </ul>"},{"location":"dev/changelog/#bug-fixes_19","title":"Bug Fixes","text":"<ul> <li>Fix a bug that egg-info directories are not removed completely, leading to incomplete distribution. #2027</li> <li>Skip distributions with wrong package meta information and duplicate path. #2075</li> <li>Avoid mistakenly passing command-line arguments while testing. #2083</li> <li>Fix a bug that lockfile groups are overwritten when running locking in a preceding step of <code>pdm install</code>. #2086</li> <li>Tolerate and actually ignore the local versions in version specifiers. #2102</li> <li>Fix a bug that shared cache cannot support overlapping namespace packages. #2105</li> </ul>"},{"location":"dev/changelog/#documentation_5","title":"Documentation","text":"<ul> <li>Add notes about using custom venv path. #2096</li> </ul>"},{"location":"dev/changelog/#release-v280a2-2023-06-30","title":"Release v2.8.0a2 (2023-06-30)","text":""},{"location":"dev/changelog/#bug-fixes_20","title":"Bug Fixes","text":"<ul> <li>Fix a bug that dependencies can't be updated when the table is separated by another table. #2056</li> <li>Fix a bug that <code>*_lock</code> hooks are always emitted with dry_run=True in <code>pdm update</code>. #2060</li> <li>Fix a bug that <code>pdm install --plugins</code> can't install self. #2062</li> <li>Fix a cache collision between named requirements and url requirements. #2064</li> </ul>"},{"location":"dev/changelog/#release-v280a1-2023-06-27","title":"Release v2.8.0a1 (2023-06-27)","text":""},{"location":"dev/changelog/#features-improvements_11","title":"Features &amp; Improvements","text":"<ul> <li>Add support for <code>cookiecutter</code> and <code>copier</code> as project generator. #2059</li> </ul>"},{"location":"dev/changelog/#release-v280a0-2023-06-27","title":"Release v2.8.0a0 (2023-06-27)","text":""},{"location":"dev/changelog/#features-improvements_12","title":"Features &amp; Improvements","text":"<ul> <li><code>pdm init</code> now accepts a template argument to initialize project from a built-in or Git template. #2053</li> <li>Replace the <code>DeprecationWarning</code> with <code>FutureWarning</code> for better exposure. #2012</li> <li>Serve <code>install-pdm.py</code> and its checksum file on the docs site. #2026</li> <li>Add new option <code>--edit/-e</code> to <code>pdm config</code> to edit the config file in default editor. #2028</li> <li>Add <code>--project</code> option to <code>pdm venv</code> to support another path as the project root. #2042</li> <li>Add support for using <code>truststore</code> as the SSL backend. This only works on Python 3.10 or newer. #2049</li> </ul>"},{"location":"dev/changelog/#bug-fixes_21","title":"Bug Fixes","text":"<ul> <li>Fix the breaking change by adding the functions back to the old location with deprecation warnings. #2013</li> <li>Fix the duplicate entries in the output of <code>pdm self list</code>. #2018</li> <li>Disable hashes caching for local files. #2019</li> <li>Populate the <code>url</code> field when converting requirements from a Pipfile-style file requirement. #2032</li> <li>Fix a bug that empty source tables in configuration files causes errors when running pdm commands. #2034</li> <li>Fix a resolution conflict caused by requested yanked version also in other transitive dependencies. #2038</li> <li>Fix a bug that binary executables are corrupted when replacing shebangs. #2045</li> <li>Do not normalize the package name when uploading to PyPI. #2057</li> </ul>"},{"location":"dev/changelog/#release-v274-2023-06-13","title":"Release v2.7.4 (2023-06-13)","text":"<p>No significant changes.</p>"},{"location":"dev/changelog/#release-v273-2023-06-13","title":"Release v2.7.3 (2023-06-13)","text":""},{"location":"dev/changelog/#bug-fixes_22","title":"Bug Fixes","text":"<ul> <li>Fix the warning of extras not found due to extra names not normalized. #2006</li> <li>Pop up a warning when the deprecated <code>parser</code> argument is passed to <code>BaseCommand.__init__()</code> method. #2007</li> <li>Fix a bug that merging settings with AoTs causing a failure. #2011</li> </ul>"},{"location":"dev/changelog/#release-v272-2023-06-12","title":"Release v2.7.2 (2023-06-12)","text":""},{"location":"dev/changelog/#features-improvements_13","title":"Features &amp; Improvements","text":"<ul> <li>Add option to expand environment variables when exporting requirements. #1997</li> </ul>"},{"location":"dev/changelog/#bug-fixes_23","title":"Bug Fixes","text":"<ul> <li>Case-insensitive sorting in <code>pdm list</code>. #1973</li> <li>Make a compatible cache reader to read the old cache files. #1981</li> <li>Fix a bug that <code>pdm init -n</code> doesn't respect the <code>--python</code> option. #1984</li> <li>Do not use the deprecated nested argument groups. #1988</li> <li>Fix an error parsing <code>setup.py</code> if it prints something to stdout. #1995</li> <li>Exclude yanked versions when running <code>install-pdm.py</code>. #1996</li> </ul>"},{"location":"dev/changelog/#release-v271-2023-06-06","title":"Release v2.7.1 (2023-06-06)","text":""},{"location":"dev/changelog/#features-improvements_14","title":"Features &amp; Improvements","text":"<ul> <li>Switch HTTP data cache to use a split body setup, where the actual body contents are not written to disk unless changed. Previously, any changed headers would write the whole body to disk again. #1971</li> <li>Show the specific install commands for different installations when checking update. This was removed before. #1972</li> </ul>"},{"location":"dev/changelog/#bug-fixes_24","title":"Bug Fixes","text":"<ul> <li>PDM ignores env vars <code>PDM_PYPI_USERNAME</code> and <code>PDM_PYPI_PASSWORD</code> when there are no defaults in config. #1961</li> <li>Guess the project name from VCS url if it is missing when importing from requirements.txt. #1970</li> <li>Correctly read the config from environment variables. #1977</li> </ul>"},{"location":"dev/changelog/#release-v270-2023-05-29","title":"Release v2.7.0 (2023-05-29)","text":""},{"location":"dev/changelog/#features-improvements_15","title":"Features &amp; Improvements","text":"<ul> <li>When keyring is available, either by importing or by CLI, the credentials of repositories and PyPI indexes will be saved into it. #1908</li> <li>Add support for reading metadata from simple index directly. #1919</li> <li>Add a configuration to specify constant command arguments for every pdm invocation. #1923</li> <li>Add ability to skip SSL verification for publish repositories via <code>repository.custom.verify_ssl</code> config option as well as new command line argument of <code>publish</code> command. #1928</li> <li>Use lazy import to reduce the startup time of the CLI. #1929</li> <li>Add the local plugin scripts to <code>PATH</code> env var. #1944</li> </ul>"},{"location":"dev/changelog/#bug-fixes_25","title":"Bug Fixes","text":"<ul> <li>Don't use install cache when installing build requirements to avoid race condition. #1869</li> <li>Fix a number of <code>ResourceWarning</code>s when running the test suite with warnings enabled. #1915</li> <li>Fix a bug that dev-dependencies group gets updated with the optional dependencies, causing the hash mismatch. #1916</li> <li>Fix format conversion error from Poetry when <code>tool.poetry.build</code> doesn't exist. #1935</li> <li>Add timeout when fetching .gitignore from GitHub. #1937</li> <li>Keep the variables in the URL credentials when exporting. #1939</li> <li>Convert to boolean when setting verify_ssl for custom indexes. #1945</li> <li><code>pdm import</code> clobbers <code>build-system.requires</code> value in <code>pyproject.toml</code>. #1948</li> </ul>"},{"location":"dev/changelog/#documentation_6","title":"Documentation","text":"<ul> <li>Update publish.md to use run instead of runs to match GitHub Actions steps documentation #1936</li> <li>Update advanced.md to use <code>pdm sync</code> instead of <code>pdm install --no-lock</code>. #1947</li> </ul>"},{"location":"dev/changelog/#release-v261-2023-05-10","title":"Release v2.6.1 (2023-05-10)","text":""},{"location":"dev/changelog/#bug-fixes_26","title":"Bug Fixes","text":"<ul> <li>Fix the error when publishing using trusted publisher. #1868</li> <li>Fix a bug that <code>PATH</code> env var isn't set correctly when running under non-isolation mode. #1904</li> </ul>"},{"location":"dev/changelog/#release-v260-2023-05-09","title":"Release v2.6.0 (2023-05-09)","text":""},{"location":"dev/changelog/#features-improvements_16","title":"Features &amp; Improvements","text":"<ul> <li>Install project-level plugins from project config, with <code>tool.pdm.plugins</code> setting. #1461</li> <li>Added a <code>--json</code> flag to both <code>run</code> and <code>info</code> command allowing to dump scripts and infos as JSON. #1854</li> <li>Consider tasks with a name starting by an underscore (<code>_</code>) as internal tasks and hide them from the listing. #1855</li> <li>When running <code>pdm init -n</code>(non-interactive mode), a venv will be created by default. Previously, the selected Python will be used under PEP 582 mode. #1862</li> <li>Support Trusted Publisher. #1868</li> <li>Add an ephemeral wheel cache in process for wheels built from non-static revision sources. #1885</li> <li>Allow self-referencing groups in dev-dependencies. #1890</li> <li>Add an option <code>--no-cross-platform</code> to <code>pdm lock</code> to create a non-cross-platform lockfile. #1898</li> </ul>"},{"location":"dev/changelog/#bug-fixes_27","title":"Bug Fixes","text":"<ul> <li>Fix brackets in <code>--venv</code> option descriptions in zsh completion script. #1847</li> <li>The resolver doesn't take into account of the requirements for both bare <code>package</code> and <code>package[extra]</code>. #1851</li> <li>Default pypi source does not use configured pypi.password, but \"\" instead. #1856 <li>Detect Python interpreters under the root of virtual environments. #1866</li> <li>Fix a race condition when the builder is creating a new build directory. #1869</li> <li>Raise <code>FileNotFoundError</code> if the requirement path is not found. #1875</li> <li>Fix a bug that the self package isn't uninstallable. #1901</li>"},{"location":"dev/changelog/#release-v256-2023-05-07","title":"Release v2.5.6 (2023-05-07)","text":""},{"location":"dev/changelog/#bug-fixes_28","title":"Bug Fixes","text":"<ul> <li>Fix a double reading issue due to cachecontrol not compatible with urllib3 2.0. #1894</li> </ul>"},{"location":"dev/changelog/#release-v255-2023-05-05","title":"Release v2.5.5 (2023-05-05)","text":"<p>No significant changes.</p>"},{"location":"dev/changelog/#release-v254-2023-05-05","title":"Release v2.5.4 (2023-05-05)","text":""},{"location":"dev/changelog/#bug-fixes_29","title":"Bug Fixes","text":"<ul> <li>Pin the urllib3 to <code>&lt;2.0</code> to avoid incompatibility with <code>cachecontrol</code>. #1886</li> </ul>"},{"location":"dev/changelog/#release-v253-2023-04-19","title":"Release v2.5.3 (2023-04-19)","text":""},{"location":"dev/changelog/#bug-fixes_30","title":"Bug Fixes","text":"<ul> <li>Fix the wrong argument validation for update command, where packages given with group option should be allowed. #1836</li> </ul>"},{"location":"dev/changelog/#documentation_7","title":"Documentation","text":"<ul> <li>Update <code>markdown-exec</code> to <code>1.5.0</code> for rendering TOC in CLI reference page. #1836</li> <li>Remove advertizing of PEP-582 from the feature highlights. Improve the anchor links for CLI reference. #1840</li> </ul>"},{"location":"dev/changelog/#release-v252-2023-04-10","title":"Release v2.5.2 (2023-04-10)","text":""},{"location":"dev/changelog/#bug-fixes_31","title":"Bug Fixes","text":"<ul> <li>Regression(#1710): Don't crash when trying to update the shebang in a binary script #1827</li> <li>Rename the env var <code>PDM_USE_VENV</code> as <code>PDM_IN_VENV</code> for <code>--venv</code> flag as it mistakenly override another existing env var. #1829</li> </ul>"},{"location":"dev/changelog/#release-v251-2023-04-09","title":"Release v2.5.1 (2023-04-09)","text":""},{"location":"dev/changelog/#bug-fixes_32","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>pdm --pep582</code> raises an argument error. #1823</li> </ul>"},{"location":"dev/changelog/#release-v250-2023-04-09","title":"Release v2.5.0 (2023-04-09)","text":""},{"location":"dev/changelog/#features-improvements_17","title":"Features &amp; Improvements","text":"<ul> <li>When <code>resolution.respect-source-order</code> is enabled, sources are lazily evaluated. This means that if a match is found on the first source, the remaining sources will not be requested. #1509</li> <li>New option <code>--venv &lt;venv&gt;</code> to run a command in the virtual environment with the given name. #1705</li> <li>Allow to prefer binary distributions when locking and installing packages, via <code>PDM_PREFER_BINARY</code> environment variable. #1817</li> </ul>"},{"location":"dev/changelog/#bug-fixes_33","title":"Bug Fixes","text":"<ul> <li>Do not validate selected groups against the locked grouped when running <code>pdm lock</code>. #1796</li> <li>Avoid duplicate .pdm-python in .gitignore. #1800</li> <li>Fix a backwards compatibility issue by adding back the <code>environment.is_global</code> property. #1814</li> <li>Fix a resolution conflict when a relative path requirement resolves to the same path as another file requirement with absolute path. #1822</li> <li>Fix an error when running <code>pdm init -p &lt;dir&gt;</code> if the target directory is not created yet. #1822</li> </ul>"},{"location":"dev/changelog/#release-v250b0-2023-03-29","title":"Release v2.5.0b0 (2023-03-29)","text":""},{"location":"dev/changelog/#breaking-changes","title":"Breaking Changes","text":"<ul> <li>Switch the default build backend to <code>pdm-backend</code>. #1684</li> <li>Only lock selected groups into the lockfile. Modify other commands to honor the groups included in the lockfile. #1704</li> <li>Move the project python path to its own file, and rename the project config file as <code>pdm.toml</code> which can be committed to the VCS. #1742</li> <li>Refactor the environment package. <code>Environment</code> is renamed to <code>PythonLocalEnvironment</code> and <code>GlobalEnvironment</code> is renamed to <code>PythonEnvironment</code>. Move <code>pdm.models.environment</code> module to <code>pdm.environments</code> package. #1791</li> </ul>"},{"location":"dev/changelog/#features-improvements_18","title":"Features &amp; Improvements","text":"<ul> <li>Add option to fail on the first install error. #1614</li> <li>Upgrade <code>unearth</code> to 0.8 to allow calling keyring from CLI. #1653</li> <li>Merge the index parameters from different configuration files. #1667</li> <li>Add new options to <code>venv</code> command to show the path or the python interpreter for a managed venv. #1680</li> <li>Write the groups of resolved dependencies to the metadata table in lockfile. #1692</li> <li>Introduce <code>--lib</code> option to <code>init</code> command to create a library project without prompting. #1708</li> <li>New command: <code>pdm fix</code> to migrate to the new PDM features. Add a hint when invoking PDM commands. #1743</li> <li>Include <code>.pdm-python</code> in project root <code>.gitignore</code> when running <code>pdm init</code>. #1749</li> <li>Allow to ignore the activated venv with <code>PDM_IGNORE_ACTIVE_VENV</code> env var. #1782</li> <li>Add a signal <code>pre_invoke</code> to emit before any command is invoked. #1792</li> </ul>"},{"location":"dev/changelog/#bug-fixes_34","title":"Bug Fixes","text":"<ul> <li>Fix a bug that install warning prints to terminal under non-verbose mode. #1635</li> <li>Fix the random failure of <code>pdm export</code> due to non-deterministic order of group iteration. #1786</li> <li>Show the actual version when running <code>pdm show --version</code> #1788</li> </ul>"},{"location":"dev/changelog/#documentation_8","title":"Documentation","text":"<ul> <li>Restructure the documentation. #1687</li> </ul>"},{"location":"dev/changelog/#dependencies_1","title":"Dependencies","text":"<ul> <li>Update <code>installer</code> to <code>0.7.0</code> and emit a warning if the RECORD validation fails. #1784</li> </ul>"},{"location":"dev/changelog/#release-v249-2023-03-16","title":"Release v2.4.9 (2023-03-16)","text":""},{"location":"dev/changelog/#bug-fixes_35","title":"Bug Fixes","text":"<ul> <li>Fix a bug of synchronization of not considering the revision of VCS requirement in comparison. #1762</li> <li>Improve the error message when parsing an invalid requirement string. #1765</li> <li>Fix a bug that <code>pdm export</code> output doesn't include the extras of the dependencies. #1767</li> </ul>"},{"location":"dev/changelog/#release-v248-2023-03-09","title":"Release v2.4.8 (2023-03-09)","text":""},{"location":"dev/changelog/#bug-fixes_36","title":"Bug Fixes","text":"<ul> <li>Fix the resolution order to prefer the packages causing the conflict.   This can make the resolution reach a solution faster. #1752</li> <li>Fix a bug that embedded credentials in URL are not respected for the default source. #1757</li> </ul>"},{"location":"dev/changelog/#release-v247-2023-03-02","title":"Release v2.4.7 (2023-03-02)","text":""},{"location":"dev/changelog/#bug-fixes_37","title":"Bug Fixes","text":"<ul> <li>Abort if lockfile isn't generated when executing <code>pdm export</code>. #1730</li> <li>Ignore <code>venv.prompt</code> configuration when using <code>conda</code> as the backend. #1734</li> <li>Fix a bug of finding local packages in the parent folder when it exists in the current folder. #1736</li> <li>Ensure UTF-8 encoding when generating README.md. #1739</li> <li>Fix a bug of show command not showing metadata of the current project. #1740</li> <li>Replace <code>.</code> with <code>-</code> when normalizing package name. #1745</li> </ul>"},{"location":"dev/changelog/#documentation_9","title":"Documentation","text":"<ul> <li>Support using <code>pdm venv activate</code> without specifying <code>env_name</code> to activate in project venv created by conda #1735</li> </ul>"},{"location":"dev/changelog/#release-v246-2023-02-20","title":"Release v2.4.6 (2023-02-20)","text":""},{"location":"dev/changelog/#bug-fixes_38","title":"Bug Fixes","text":"<ul> <li>Fix a resolution failure when the project has cascading relative path dependencies. #1702</li> <li>Don't crash when trying to update the shebang in a binary script. #1709</li> <li>Handle the legacy specifiers that is unable to parse with packaging&gt;22.0. #1719</li> <li>Fix the setup.py parser to ignore the expressions unable to parse as a string. This is safe for initializing a requirement. #1720</li> <li>Fix a bug converting from flit metadata when the source file can't be found. #1726</li> </ul>"},{"location":"dev/changelog/#documentation_10","title":"Documentation","text":"<ul> <li>Add config example for Emacs using eglot + pyright #1721</li> </ul>"},{"location":"dev/changelog/#miscellany_1","title":"Miscellany","text":"<ul> <li>Use <code>ruff</code> as the linter. #1715</li> <li>Document installation via <code>asdf</code>. #1725</li> </ul>"},{"location":"dev/changelog/#release-v245-2023-02-10","title":"Release v2.4.5 (2023-02-10)","text":""},{"location":"dev/changelog/#bug-fixes_39","title":"Bug Fixes","text":"<ul> <li>Fix a bug that built wheels are prioritized over source distributions with higher version number. #1698</li> </ul>"},{"location":"dev/changelog/#release-v244-2023-02-10","title":"Release v2.4.4 (2023-02-10)","text":""},{"location":"dev/changelog/#features-improvements_19","title":"Features &amp; Improvements","text":"<ul> <li>Add more intuitive error message when the <code>requires-python</code> doesn't work for all dependencies. #1690</li> </ul>"},{"location":"dev/changelog/#bug-fixes_40","title":"Bug Fixes","text":"<ul> <li>Prefer built distributions when finding packages for metadata extraction. #1535</li> </ul>"},{"location":"dev/changelog/#release-v243-2023-02-06","title":"Release v2.4.3 (2023-02-06)","text":""},{"location":"dev/changelog/#features-improvements_20","title":"Features &amp; Improvements","text":"<ul> <li>Allow creating venv in project forcely if it already exists. #1666</li> <li>Always ignore remembered selection in pdm init. #1672</li> </ul>"},{"location":"dev/changelog/#bug-fixes_41","title":"Bug Fixes","text":"<ul> <li>Fix the fallback build backend to <code>pdm-pep517</code> instead of <code>setuptools</code>. #1658</li> <li>Eliminate the deprecation warnings from <code>importlib.resources</code>. #1660</li> <li>Don't crash when failed to get the latest version of PDM for checking update. #1663</li> <li>Fix the priorities of importable formats to make sure the correct format is used. #1669</li> <li>Import editable requirements into dev dependencies. #1674</li> </ul>"},{"location":"dev/changelog/#release-v242-2023-01-31","title":"Release v2.4.2 (2023-01-31)","text":""},{"location":"dev/changelog/#bug-fixes_42","title":"Bug Fixes","text":"<ul> <li>Skip some tests on packaging &lt; 22. #1649</li> <li>Fix a bug that sources from the project config are not loaded. #1651</li> <li>Set VIRTUAL_ENV in <code>pdm run</code>. #1652</li> </ul>"},{"location":"dev/changelog/#release-v241-2023-01-28","title":"Release v2.4.1 (2023-01-28)","text":""},{"location":"dev/changelog/#features-improvements_21","title":"Features &amp; Improvements","text":"<ul> <li>Add proper display for the extra pypi sources in <code>pdm config</code>. #1622</li> <li>Support running python scripts without prefixing with <code>python</code>. #1626</li> </ul>"},{"location":"dev/changelog/#bug-fixes_43","title":"Bug Fixes","text":"<ul> <li>Ignore the python requirement for overriden packages. #1575</li> <li>Fix the wildcards in requirement specifiers to make it pass the new parser of <code>packaging&gt;=22</code>. #1619</li> <li>Add the missing <code>subdirectory</code> attribute to the lockfile entry. #1630</li> <li>Fix a bug that VCS locks don't update when the rev part changes. #1640</li> <li>Redirect the spinner output to stderr. #1646</li> <li>Ensure the destination directory exists before building the packages. #1647</li> </ul>"},{"location":"dev/changelog/#release-v240-2023-01-12","title":"Release v2.4.0 (2023-01-12)","text":""},{"location":"dev/changelog/#features-improvements_22","title":"Features &amp; Improvements","text":"<ul> <li>Support multiple PyPI indexes in the configuration. They will be tried after the sources in <code>pyproject.toml</code>. #1310</li> <li>Accept yanked versions when the requirement version is pinned. #1575</li> <li>Expose PDM fixtures as a <code>pytest</code> plugin <code>pdm.pytest</code> for plugin developers. #1594</li> <li>Show message in the status when fetching package hashes.   Fetch hashes from the JSON API response as well. #1609</li> <li>Mark <code>pdm.lock</code> with an <code>@generated</code> comment. #1611</li> </ul>"},{"location":"dev/changelog/#bug-fixes_44","title":"Bug Fixes","text":"<ul> <li>Exclude site-packages for symlinks of the python interpreter as well. #1598</li> <li>Fix a bug that error output can't be decoded correctly on Windows. #1602</li> </ul>"},{"location":"dev/changelog/#release-v234-2022-12-27","title":"Release v2.3.4 (2022-12-27)","text":""},{"location":"dev/changelog/#features-improvements_23","title":"Features &amp; Improvements","text":"<ul> <li>Detect PDM inside a zipapp and disable some functions. #1578</li> </ul>"},{"location":"dev/changelog/#bug-fixes_45","title":"Bug Fixes","text":"<ul> <li>Don't write <code>sitecustomize</code> to the home directory if it exists in the filesystem(not packed in a zipapp). #1572</li> <li>Fix a bug that a directory is incorrectly marked as to be deleted when it contains symlinks. #1580</li> </ul>"},{"location":"dev/changelog/#release-v233-2022-12-15","title":"Release v2.3.3 (2022-12-15)","text":""},{"location":"dev/changelog/#bug-fixes_46","title":"Bug Fixes","text":"<ul> <li>Allow relative paths in <code>build-system.requires</code>, since <code>build</code> and <code>hatch</code> both support it. Be aware it is not allowed in the standard. #1560</li> <li>Strip the local part when building a specifier for comparison with the package version. This is not permitted by PEP 508 as implemented by <code>packaging 22.0</code>. #1562</li> <li>Update the version for check_update after self update #1563</li> <li>Replace the <code>__file__</code> usages with <code>importlib.resources</code>, to make PDM usable in a zipapp. #1567</li> <li>Fix the matching problem of packages in the lockfile. #1569</li> </ul>"},{"location":"dev/changelog/#dependencies_2","title":"Dependencies","text":"<ul> <li>Exclude <code>package==22.0</code> from the dependencies to avoid some breakages to the end users. #1568</li> </ul>"},{"location":"dev/changelog/#release-v232-2022-12-08","title":"Release v2.3.2 (2022-12-08)","text":""},{"location":"dev/changelog/#bug-fixes_47","title":"Bug Fixes","text":"<ul> <li>Fix an installation failure when the RECORD file contains commas in the file path. #1010</li> <li>Fallback to <code>pdm.pep517</code> as the metadata transformer for unknown custom build backends. #1546</li> <li>Fix a bug that Ctrl + C kills the python interactive session instead of clearing the current line. #1547</li> <li>Fix a bug with egg segment for local dependency #1552</li> </ul>"},{"location":"dev/changelog/#dependencies_3","title":"Dependencies","text":"<ul> <li>Update <code>installer</code> to <code>0.6.0</code>. #1550</li> <li>Update minimum version of <code>unearth</code> to <code>0.6.3</code> and test against <code>packaging==22.0</code>. #1555</li> </ul>"},{"location":"dev/changelog/#release-v231-2022-12-05","title":"Release v2.3.1 (2022-12-05)","text":""},{"location":"dev/changelog/#bug-fixes_48","title":"Bug Fixes","text":"<ul> <li>Fix a resolution loop issue when the current project depends on itself and it uses the dynamic version from SCM. #1541</li> <li>Don't give duplicate results when specifying a relative path for <code>pdm use</code>. #1542</li> </ul>"},{"location":"dev/changelog/#release-v230-2022-12-02","title":"Release v2.3.0 (2022-12-02)","text":""},{"location":"dev/changelog/#features-improvements_24","title":"Features &amp; Improvements","text":"<ul> <li>Beautify the error message of build errors. Default to showing the last 10 lines of the build output. #1491</li> <li>Rename the <code>tool.pdm.overrides</code> table to <code>tool.pdm.resolution.overrides</code>. The old name is deprecated at the same time. #1503</li> <li>Add backend selection and <code>--backend</code> option to <code>pdm init</code> command, users can choose a favorite backend from <code>setuptools</code>, <code>flit</code>, <code>hatchling</code> and <code>pdm-pep517</code>(default), since they all support PEP 621 standards. #1504</li> <li>Allows specifying the insertion position of user provided arguments in scripts with the <code>{args[:default]}</code> placeholder. #1507</li> </ul>"},{"location":"dev/changelog/#bug-fixes_49","title":"Bug Fixes","text":"<ul> <li>The local package is now treated specially during installation and locking. This means it will no longer be included in the lockfile, and should never be installed twice even when using nested extras. This will ensure the lockdown stays relevant when the version changes. #1481</li> <li>Fix the version diff algorithm of installed packages to consider local versions as compatible. #1497</li> <li>Fix the confusing message when detecting a Python interpreter under <code>python.use_venv=False</code> #1508</li> <li>Fix the test failure with the latest <code>findpython</code> installed. #1516</li> <li>Fix the module missing error of pywin32 in a virtualenv with <code>install.cache</code> set to <code>true</code> and caching method is <code>pth</code>. #863</li> </ul>"},{"location":"dev/changelog/#dependencies_4","title":"Dependencies","text":"<ul> <li>Drop the dependency <code>pdm-pep517</code>. #1504</li> <li>Replace <code>pep517</code> with <code>pyproject-hooks</code> because of the rename. #1528</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_2","title":"Removals and Deprecations","text":"<ul> <li>Remove the support for exporting the project file to a <code>setup.py</code> format, users are encouraged to migrate to the PEP 621 metadata. #1504</li> </ul>"},{"location":"dev/changelog/#release-v221-2022-11-03","title":"Release v2.2.1 (2022-11-03)","text":""},{"location":"dev/changelog/#features-improvements_25","title":"Features &amp; Improvements","text":"<ul> <li>Make <code>sitecustomize.py</code> respect the <code>PDM_PROJECT_MAX_DEPTH</code> environment variable #1471</li> </ul>"},{"location":"dev/changelog/#bug-fixes_50","title":"Bug Fixes","text":"<ul> <li>Fix the comparison of <code>python_version</code> in the environment marker. When the version contains only one digit, the result was incorrect. #1484</li> </ul>"},{"location":"dev/changelog/#release-v220-2022-10-31","title":"Release v2.2.0 (2022-10-31)","text":""},{"location":"dev/changelog/#features-improvements_26","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>venv.prompt</code> configuration to allow customizing prompt when a virtualenv is activated #1332</li> <li>Allow the use of custom CA certificates per publish repository using <code>ca_certs</code> or from the command line via <code>pdm publish --ca-certs &lt;path&gt; ...</code>. #1392</li> <li>Rename the <code>plugin</code> command to <code>self</code>, and it can not only manage plugins but also all dependencies. Add a subcommand <code>self update</code> to update PDM itself. #1406</li> <li>Allow <code>pdm init</code> to receive a Python path or version via <code>--python</code> option. #1412</li> <li>Add a default value for <code>requires-python</code> when importing from other formats. #1426</li> <li>Use <code>pdm</code> instead of <code>pip</code> to resolve and install build requirements. So that PDM configurations can control the process. #1429</li> <li>Customizable color theme via <code>pdm config</code> command. #1450</li> <li>A new <code>pdm lock --check</code> flag to validate whether the lock is up to date. #1459</li> <li>Add both option and config item to ship <code>pip</code> when creating a new venv. #1463</li> <li>Issue warning and skip the requirement if it has the same name as the current project. #1466</li> <li>Enhance the <code>pdm list</code> command with new formats: <code>--csv,--markdown</code> and add options <code>--fields,--sort</code> to control the output contents. Users can also include <code>licenses</code> in the <code>--fields</code> option to display the package licenses. #1469</li> <li>A new pre-commit hook to run <code>pdm lock --check</code> in pre-commit. #1471</li> </ul>"},{"location":"dev/changelog/#bug-fixes_51","title":"Bug Fixes","text":"<ul> <li>Fix the issue that relative paths don't work well with <code>--project</code> argument. #1220</li> <li>It is now possible to refer to a package from outside the project with relative paths in dependencies. #1381</li> <li>Ensure <code>pypi.[ca,client]_cert[s]</code> config items are passed to distribution builder install steps to allow for custom PyPI index sources with self signed certificates. #1396</li> <li>Fix a crash issue when depending on editable packages with extras. #1401</li> <li>Do not save the python path when using non-interactive mode in <code>pdm init</code>. #1410</li> <li>Fix the matching of <code>python*</code> command in <code>pdm run</code>. #1414</li> <li>Show the Python path, instead of the real executable, in the Python selection menu. #1418</li> <li>Fix the HTTP client of package publishment to prompt for password and read PDM configurations correctly. #1430</li> <li>Ignore the unknown fields when constructing a requirement object. #1445</li> <li>Fix a bug of unrelated candidates being fetched if the requirement is matching wildcard versions(e.g. <code>==1.*</code>). #1465</li> <li>Use <code>importlib-metadata</code> from PyPI for Python &lt; 3.10. #1467</li> </ul>"},{"location":"dev/changelog/#documentation_11","title":"Documentation","text":"<ul> <li>Clarify the difference between a library and an application. Update the guide of multi-stage docker build. #1371</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_3","title":"Removals and Deprecations","text":"<ul> <li>Remove all top-level imports, users should import from the submodules instead. #1404</li> <li>Remove the usages of old config names deprecated since 2.0. #1422</li> <li>Remove the deprecated color functions, use rich's console markup instead. #1452</li> </ul>"},{"location":"dev/changelog/#release-v215-2022-10-05","title":"Release v2.1.5 (2022-10-05)","text":""},{"location":"dev/changelog/#bug-fixes_52","title":"Bug Fixes","text":"<ul> <li>Ensure <code>pypi.[ca,client]_cert[s]</code> config items are passed to distribution builder install steps to allow for custom PyPI index sources with self signed certificates. #1396</li> <li>Fix a crash issue when depending on editable packages with extras. #1401</li> <li>Do not save the python path when using non-interactive mode in <code>pdm init</code>. #1410</li> <li>Restrict importlib-metadata (&lt;5.0.0) for Python &lt;3.8 #1411</li> </ul>"},{"location":"dev/changelog/#release-v214-2022-09-17","title":"Release v2.1.4 (2022-09-17)","text":""},{"location":"dev/changelog/#bug-fixes_53","title":"Bug Fixes","text":"<ul> <li>Fix a lock failure when depending on self with URL requirements. #1347</li> <li>Ensure list to concatenate args for composite scripts. #1359</li> <li>Fix an error in <code>pdm lock --refresh</code> if some packages has URLs. #1361</li> <li>Fix unnecessary package downloads and VCS clones for certain commands. #1370</li> <li>Fix a conversion error when converting a list of conditional dependencies from a Poetry format. #1383</li> </ul>"},{"location":"dev/changelog/#documentation_12","title":"Documentation","text":"<ul> <li>Adds a section to the docs on how to correctly work with PDM and version control systems. #1364</li> </ul>"},{"location":"dev/changelog/#release-v213-2022-08-30","title":"Release v2.1.3 (2022-08-30)","text":""},{"location":"dev/changelog/#features-improvements_27","title":"Features &amp; Improvements","text":"<ul> <li>When adding a package to (or removing from) a group, enhance the formatting of the group name in the printed message. #1329</li> </ul>"},{"location":"dev/changelog/#bug-fixes_54","title":"Bug Fixes","text":"<ul> <li>Fix a bug of missing hashes for packages with <code>file://</code> links the first time they are added. #1325</li> <li>Ignore invalid values of <code>data-requires-python</code> when parsing package links. #1334</li> <li>Leave an incomplete project metadata if PDM fails to parse the project files, but emit a warning. #1337</li> <li>Fix the bug that <code>editables</code> package isn't installed for self package. #1344</li> <li>Fix a decoding error for non-ASCII characters in package description when publishing it. #1345</li> </ul>"},{"location":"dev/changelog/#documentation_13","title":"Documentation","text":"<ul> <li>Clarify documentation explaining <code>setup-script</code>, <code>run-setuptools</code>, and <code>is-purelib</code>. #1327</li> </ul>"},{"location":"dev/changelog/#release-v212-2022-08-15","title":"Release v2.1.2 (2022-08-15)","text":""},{"location":"dev/changelog/#bug-fixes_55","title":"Bug Fixes","text":"<ul> <li>Fix a bug that dependencies from different versions of the same package override each other. #1307</li> <li>Forward SIGTERM to child processes in <code>pdm run</code>. #1312</li> <li>Fix errors when running on FIPS 140-2 enabled systems using Python 3.9 and newer. #1313</li> <li>Fix the build failure when the subprocess outputs with non-UTF8 characters. #1319</li> <li>Delay the trigger of <code>post_lock</code> for <code>add</code> and <code>update</code> operations, to ensure the <code>pyproject.toml</code> is updated before the hook is run. #1320</li> </ul>"},{"location":"dev/changelog/#release-v211-2022-08-05","title":"Release v2.1.1 (2022-08-05)","text":""},{"location":"dev/changelog/#features-improvements_28","title":"Features &amp; Improvements","text":"<ul> <li>Add a env_file.override option that allows the user to specify that   the env_file should override any existing environment variables. This   is not the default as the environment the code runs it should take   precedence. #1299</li> </ul>"},{"location":"dev/changelog/#bug-fixes_56","title":"Bug Fixes","text":"<ul> <li>Fix a bug that unnamed requirements can't override the old ones in either <code>add</code> or <code>update</code> command. #1287</li> <li>Support mutual TLS to private repositories via pypi.client_cert and pypi.client_key config options. #1290</li> <li>Set a minimum version for the <code>packaging</code> dependency to ensure that <code>packaging.utils.parse_wheel_filename</code> is available. #1293</li> <li>Fix a bug that checking for PDM update creates a venv. #1301</li> <li>Prefer compatible packages when fetching metadata. #1302</li> </ul>"},{"location":"dev/changelog/#release-v210-2022-07-29","title":"Release v2.1.0 (2022-07-29)","text":""},{"location":"dev/changelog/#features-improvements_29","title":"Features &amp; Improvements","text":"<ul> <li>Allow the use of custom CA certificates using the <code>pypi.ca_certs</code> config entry. #1240</li> <li>Add <code>pdm export</code> to available pre-commit hooks. #1279</li> </ul>"},{"location":"dev/changelog/#bug-fixes_57","title":"Bug Fixes","text":"<ul> <li>Skip incompatible requirements when installing build dependencies. #1264</li> <li>Fix a crash when pdm tries to publish a package with non-ASCII characters in the metadata. #1270</li> <li>Try to read the lock file even if the lock version is incompatible. #1273</li> <li>For packages that are only available as source distribution, the <code>summary</code> field in <code>pdm.lock</code> contains the <code>description</code> from the package's <code>pyproject.toml</code>. #1274</li> <li>Do not crash when calling <code>pdm show</code> for a package that is only available as source distribution. #1276</li> <li>Fix a bug that completion scripts are interpreted as rich markups. #1283</li> </ul>"},{"location":"dev/changelog/#dependencies_5","title":"Dependencies","text":"<ul> <li>Remove the dependency of <code>pip</code>. #1268</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_4","title":"Removals and Deprecations","text":"<ul> <li>Deprecate the top-level imports from <code>pdm</code> module, it will be removed in the future. #1282</li> </ul>"},{"location":"dev/changelog/#release-v203-2022-07-22","title":"Release v2.0.3 (2022-07-22)","text":""},{"location":"dev/changelog/#bug-fixes_58","title":"Bug Fixes","text":"<ul> <li>Support Conda environments when detecting the project environment. #1253</li> <li>Fix the interpreter resolution to first try <code>python</code> executable in the <code>PATH</code>. #1255</li> <li>Stabilize sorting of URLs in <code>metadata.files</code> in <code>pdm.lock</code>. #1256</li> <li>Don't expand credentials in the file URLs in the <code>[metada.files]</code> table of the lock file. #1259</li> </ul>"},{"location":"dev/changelog/#release-v202-2022-07-20","title":"Release v2.0.2 (2022-07-20)","text":""},{"location":"dev/changelog/#features-improvements_30","title":"Features &amp; Improvements","text":"<ul> <li><code>env_file</code> variables no longer override existing environment variables. #1235</li> <li>Support referencing other optional groups in optional-dependencies with <code>&lt;this_package_name&gt;[group1, group2]</code> #1241</li> </ul>"},{"location":"dev/changelog/#bug-fixes_59","title":"Bug Fixes","text":"<ul> <li>Respect <code>requires-python</code> when creating the default venv. #1237</li> </ul>"},{"location":"dev/changelog/#release-v201-2022-07-17","title":"Release v2.0.1 (2022-07-17)","text":""},{"location":"dev/changelog/#bug-fixes_60","title":"Bug Fixes","text":"<ul> <li>Write lockfile before calling 'post_lock' hook #1224</li> <li>Suppress errors when cache dir isn't accessible. #1226</li> <li>Don't save python path for venv commands. #1230</li> </ul>"},{"location":"dev/changelog/#release-v200-2022-07-15","title":"Release v2.0.0 (2022-07-15)","text":""},{"location":"dev/changelog/#bug-fixes_61","title":"Bug Fixes","text":"<ul> <li>Fix a bug that the running env overrides the PEP 582 <code>PYTHONPATH</code>. #1211</li> <li>Add <code>pwsh</code> as an alias of <code>powershell</code> for shell completion. #1216</li> <li>Fixed a bug with <code>zsh</code> completion regarding <code>--pep582</code> flag. #1218</li> <li>Fix a bug of requirement checking under non-isolated mode. #1219</li> <li>Fix a bug when removing packages, TOML document might become invalid. #1221</li> </ul>"},{"location":"dev/changelog/#release-v200b2-2022-07-08","title":"Release v2.0.0b2 (2022-07-08)","text":""},{"location":"dev/changelog/#breaking-changes_1","title":"Breaking Changes","text":"<ul> <li>Store file URLs instead of filenames in the lock file, bump lock version to <code>4.0</code>. #1203</li> </ul>"},{"location":"dev/changelog/#features-improvements_31","title":"Features &amp; Improvements","text":"<ul> <li>Read site-wide configuration, which serves as the lowest-priority layer.   This layer will be read-only in the CLI. #1200</li> <li>Get package links from the urls stored in the lock file. #1204</li> </ul>"},{"location":"dev/changelog/#bug-fixes_62","title":"Bug Fixes","text":"<ul> <li>Fix a bug that the host pip(installed with pdm) may not be compatible with the project python. #1196</li> <li>Update <code>unearth</code> to fix a bug that install links with weak hashes are skipped. This often happens on self-hosted PyPI servers. #1202</li> </ul>"},{"location":"dev/changelog/#release-v200b1-2022-07-02","title":"Release v2.0.0b1 (2022-07-02)","text":""},{"location":"dev/changelog/#features-improvements_32","title":"Features &amp; Improvements","text":"<ul> <li>Integrate <code>pdm venv</code> commands into the main program. Make PEP 582 an opt-in feature. #1162</li> <li>Add config <code>global_project.fallback_verbose</code> defaulting to <code>True</code>. When set to <code>False</code> disables message <code>Project is not found, fallback to the global project</code> #1188</li> <li>Add <code>--only-keep</code> option to <code>pdm sync</code> to keep only selected packages. Originally requested at #398. #1191</li> </ul>"},{"location":"dev/changelog/#bug-fixes_63","title":"Bug Fixes","text":"<ul> <li>Fix a bug that requirement extras and underlying are resolved to the different version #1173</li> <li>Update <code>unearth</code> to <code>0.4.1</code> to skip the wheels with invalid version parts. #1178</li> <li>Fix reading <code>PDM_RESOLVE_MAX_ROUNDS</code> environment variable (was spelled <code>\u2026ROUDNS</code> before). #1180</li> <li>Deduplicate the list of found Python versions. #1182</li> <li>Use the normal stream handler for logging, to fix some display issues under non-tty environments. #1184</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_5","title":"Removals and Deprecations","text":"<ul> <li>Remove the useless <code>--no-clean</code> option from <code>pdm sync</code> command. #1191</li> </ul>"},{"location":"dev/changelog/#release-v200a1-2022-06-29","title":"Release v2.0.0a1 (2022-06-29)","text":""},{"location":"dev/changelog/#breaking-changes_2","title":"Breaking Changes","text":"<ul> <li>Editable dependencies in the <code>[project]</code> table is not allowed, according to PEP 621. They are however still allowed in the <code>[tool.pdm.dev-dependencies]</code> table. PDM will emit a warning when it finds editable dependencies in the <code>[project]</code> table, or will abort when you try to add them into the <code>[project]</code> table via CLI. #1083</li> <li>Now the paths to the global configurations and global project are calculated according to platform standards. #1161</li> </ul>"},{"location":"dev/changelog/#features-improvements_33","title":"Features &amp; Improvements","text":"<ul> <li>Add support for importing from a <code>setup.py</code> project. #1062</li> <li>Switch the UI backend to <code>rich</code>. #1091</li> <li>Improved the terminal UI and logging. Disable live progress under verbose mode. The logger levels can be controlled by the <code>-v</code> option. #1096</li> <li>Use <code>unearth</code> to replace <code>pip</code>'s <code>PackageFinder</code> and related data models. PDM no longer relies on <code>pip</code> internals, which are unstable across updates. #1096</li> <li>Lazily load the candidates returned by <code>find_matches()</code> to speed up the resolution. #1098</li> <li>Add a new command <code>publish</code> to PDM since it is required for so many people and it will make the workflow easier. #1107</li> <li>Add a <code>composite</code> script kind allowing to run multiple defined scripts in a single command as well as reusing scripts but overriding <code>env</code> or <code>env_file</code>. #1117</li> <li>Add a new execution option <code>--skip</code> to opt-out some scripts and hooks from any execution (both scripts and PDM commands). #1127</li> <li>Add the <code>pre/post_publish</code>, <code>pre/post_run</code> and <code>pre/post_script</code> hooks as well as an extensive lifecycle and hooks documentation. #1147</li> <li>Shorter scripts listing, especially for multilines and composite scripts. #1151</li> <li>Build configurations have been moved to <code>[tool.pdm.build]</code>, according to <code>pdm-pep517 1.0.0</code>. At the same time, warnings will be shown against old usages. #1153</li> <li>Improve the lock speed by parallelizing the hash fetching. #1154</li> <li>Retrieve the candidate metadata by parsing the <code>pyproject.toml</code> rather than building it. #1156</li> <li>Update the format converters to support the new <code>[tool.pdm.build]</code> table. #1157</li> <li>Scripts are now available as root command if they don't conflict with any builtin or plugin-contributed command. #1159</li> <li>Add a <code>post_use</code> hook triggered after successfully switching Python version. #1163</li> <li>Add project configuration <code>respect-source-order</code> under <code>[tool.pdm.resolution]</code> to respect the source order in the <code>pyproject.toml</code> file. Packages will be returned by source earlier in the order or later ones if not found. #593</li> </ul>"},{"location":"dev/changelog/#bug-fixes_64","title":"Bug Fixes","text":"<ul> <li>Fix a bug that candidates with local part in the version can't be found and installed correctly. #1093</li> </ul>"},{"location":"dev/changelog/#dependencies_6","title":"Dependencies","text":"<ul> <li>Prefer <code>tomllib</code> on Python 3.11 #1072</li> <li>Drop the vendored libraries <code>click</code>, <code>halo</code>, <code>colorama</code> and <code>log_symbols</code>. PDM has no vendors now. #1091</li> <li>Update dependency version <code>pdm-pep517</code> to <code>1.0.0</code>. #1153</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_6","title":"Removals and Deprecations","text":"<ul> <li>PDM legacy metadata format(from <code>pdm 0.x</code>) is no longer supported. #1157</li> </ul>"},{"location":"dev/changelog/#miscellany_2","title":"Miscellany","text":"<ul> <li>Provide a <code>tox.ini</code> file for easier local testing against all Python versions. #1160</li> </ul>"},{"location":"dev/changelog/#release-v1154-2022-06-28","title":"Release v1.15.4 (2022-06-28)","text":""},{"location":"dev/changelog/#bug-fixes_65","title":"Bug Fixes","text":"<ul> <li>Revert #1106: Do not use <code>venv</code> scheme for <code>prefix</code> kind install scheme. #1158</li> <li>Fix a bug when updating a package with extra requirements, the package version doesn't get updated correctly. #1166</li> </ul>"},{"location":"dev/changelog/#miscellany_3","title":"Miscellany","text":"<ul> <li>Add additional installation option via asdf-pdm.   Add <code>skip-add-to-path</code> option to installer in order to prevent changing <code>PATH</code>.   Replace <code>bin</code> variable name with <code>bin_dir</code>. #1145</li> </ul>"},{"location":"dev/changelog/#release-v1153-2022-06-14","title":"Release v1.15.3 (2022-06-14)","text":""},{"location":"dev/changelog/#bug-fixes_66","title":"Bug Fixes","text":"<ul> <li>Fix a defect in the resolution preferences that causes an infinite resolution loop. #1119</li> <li>Update the poetry importer to support the new <code>[tool.poetry.build]</code> config table. #1131</li> </ul>"},{"location":"dev/changelog/#improved-documentation","title":"Improved Documentation","text":"<ul> <li>Add support for multiple versions of documentations. #1126</li> </ul>"},{"location":"dev/changelog/#release-v1152-2022-06-06","title":"Release v1.15.2 (2022-06-06)","text":""},{"location":"dev/changelog/#bug-fixes_67","title":"Bug Fixes","text":"<ul> <li>Fix bug where SIGINT is sent to the main <code>pdm</code> process and not to the process actually being run. #1095</li> <li>Fix a bug due to the build backend fallback, which causes different versions of the same requirement to exist in the build environment, making the building unstable depending on which version being used. #1099</li> <li>Don't include the <code>version</code> in the cache key of the locked candidates if they are from a URL requirement. #1099</li> <li>Fix a bug where dependencies with <code>requires-python</code> pre-release versions caused <code>pdm update</code> to fail with <code>InvalidPyVersion</code>. #1111</li> </ul>"},{"location":"dev/changelog/#release-v1151-2022-06-02","title":"Release v1.15.1 (2022-06-02)","text":""},{"location":"dev/changelog/#bug-fixes_68","title":"Bug Fixes","text":"<ul> <li>Fix a bug that dependencies are missing from the dep graph when they are depended by a requirement with extras. #1097</li> <li>Give a default version if the version is dynamic in <code>setup.cfg</code> or <code>setup.py</code>. #1101</li> <li>Fix a bug that the hashes for file URLs are not included in the lock file. #1103</li> <li>Fix a bug that package versions are updated even when they are excluded by <code>pdm update</code> command. #1104</li> <li>Prefer <code>venv</code> install scheme when available. This scheme is more stable than <code>posix_prefix</code> scheme since the latter is often patched by distributions. #1106</li> </ul>"},{"location":"dev/changelog/#miscellany_4","title":"Miscellany","text":"<ul> <li>Move the test artifacts to a submodule. It will make it easier to package this project. #1084</li> </ul>"},{"location":"dev/changelog/#release-v1150-2022-05-16","title":"Release v1.15.0 (2022-05-16)","text":""},{"location":"dev/changelog/#features-improvements_34","title":"Features &amp; Improvements","text":"<ul> <li>Allow specifying lockfile other than <code>pdm.lock</code> by <code>--lockfile</code> option or <code>PDM_LOCKFILE</code> env var. #1038</li> </ul>"},{"location":"dev/changelog/#bug-fixes_69","title":"Bug Fixes","text":"<ul> <li>Replace the editable entry in <code>pyproject.toml</code> when running <code>pdm add --no-editable &lt;package&gt;</code>. #1050</li> <li>Ensure the pip module inside venv in installation script. #1053</li> <li>Fix the py2 compatibility issue in the in-process <code>get_sysconfig_path.py</code> script. #1056</li> <li>Fix a bug that file paths in URLs are not correctly unquoted. #1073</li> <li>Fix a bug on Python 3.11 that overriding an existing command from plugins raises an error. #1075</li> <li>Replace the <code>${PROJECT_ROOT}</code> variable in the result of <code>export</code> command. #1079</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_7","title":"Removals and Deprecations","text":"<ul> <li>Show a warning if Python 2 interpreter is being used and remove the support on 2.0. #1082</li> </ul>"},{"location":"dev/changelog/#release-v1141-2022-04-21","title":"Release v1.14.1 (2022-04-21)","text":""},{"location":"dev/changelog/#features-improvements_35","title":"Features &amp; Improvements","text":"<ul> <li>Ask for description when doing <code>pdm init</code> and create default README for libraries. #1041</li> </ul>"},{"location":"dev/changelog/#bug-fixes_70","title":"Bug Fixes","text":"<ul> <li>Fix a bug of missing subdirectory fragment when importing from a <code>requirements.txt</code>. #1036</li> <li>Fix use_cache.json with corrupted python causes <code>pdm use</code> error. #1039</li> <li>Ignore the <code>optional</code> key when converting from Poetry's dependency entries. #1042</li> </ul>"},{"location":"dev/changelog/#improved-documentation_1","title":"Improved Documentation","text":"<ul> <li>Clarify documentation on enabling PEP582 globally. #1033</li> </ul>"},{"location":"dev/changelog/#release-v1140-2022-04-08","title":"Release v1.14.0 (2022-04-08)","text":""},{"location":"dev/changelog/#features-improvements_36","title":"Features &amp; Improvements","text":"<ul> <li>Editable installations won't be overridden unless <code>--no-editable</code> is passed.   <code>pdm add --no-editable</code> will now override the <code>editable</code> mode of the given packages. #1011</li> <li>Re-calculate the file hashes when running <code>pdm lock --refresh</code>. #1019</li> </ul>"},{"location":"dev/changelog/#bug-fixes_71","title":"Bug Fixes","text":"<ul> <li>Fix a bug that requirement with extras isn't resolved to the version as specified by the range. #1001</li> <li>Replace the <code>${PROJECT_ROOT}</code> in the output of <code>pdm list</code>. #1004</li> <li>Further fix the python path issue of macOS system installed Python. #1023</li> <li>Fix the install path issue on Python 3.10 installed from homebrew. #996</li> </ul>"},{"location":"dev/changelog/#improved-documentation_2","title":"Improved Documentation","text":"<ul> <li>Document how to install PDM inside a project with Pyprojectx. #1004</li> </ul>"},{"location":"dev/changelog/#dependencies_7","title":"Dependencies","text":"<ul> <li>Support <code>installer 0.5.x</code>. #1002</li> </ul>"},{"location":"dev/changelog/#release-v1136-2022-03-28","title":"Release v1.13.6 (2022-03-28)","text":""},{"location":"dev/changelog/#bug-fixes_72","title":"Bug Fixes","text":"<ul> <li>Default the optional <code>license</code> field to \"None\". #991</li> <li>Don't create project files in <code>pdm search</code> command. #993</li> <li>Fix a bug that the env vars in source urls in exported result are not expanded. #997</li> </ul>"},{"location":"dev/changelog/#release-v1135-2022-03-23","title":"Release v1.13.5 (2022-03-23)","text":""},{"location":"dev/changelog/#features-improvements_37","title":"Features &amp; Improvements","text":"<ul> <li>Users can change the install destination of global project to the user site(<code>~/.local</code>) with <code>global_project.user_site</code> config. #885</li> <li>Make the path to the global project configurable. Rename the configuration <code>auto_global</code> to <code>global_project.fallback</code> and deprecate the old name. #986</li> </ul>"},{"location":"dev/changelog/#bug-fixes_73","title":"Bug Fixes","text":"<ul> <li>Fix the compatibility when fetching license information in <code>show</code> command. #966</li> <li>Don't follow symlinks for the paths in the requirement strings. #976</li> <li>Use the default install scheme when installing build requirements. #983</li> <li>Fix a bug that <code>_.site_packages</code> is overridden by default option value. #985</li> </ul>"},{"location":"dev/changelog/#release-v1134-2022-03-09","title":"Release v1.13.4 (2022-03-09)","text":""},{"location":"dev/changelog/#features-improvements_38","title":"Features &amp; Improvements","text":"<ul> <li>Update the dependency <code>pdm-pep517</code> to support PEP 639. #959</li> </ul>"},{"location":"dev/changelog/#bug-fixes_74","title":"Bug Fixes","text":"<ul> <li>Filter out the unmatched python versions when listing the available versions. #941</li> <li>Fix a bug displaying the available python versions. #943</li> <li>Fix a bug under non-UTF8 console encoding. #960</li> <li>Fix a bug that data files are not copied to the destination when using installation cache. #961</li> </ul>"},{"location":"dev/changelog/#release-v1133-2022-02-24","title":"Release v1.13.3 (2022-02-24)","text":""},{"location":"dev/changelog/#bug-fixes_75","title":"Bug Fixes","text":"<ul> <li>Fix a bug that VCS repo name are parsed as the package name. #928</li> <li>Support prerelease versions for global projects. #932</li> <li>Fix a bug that VCS revision in the lock file isn't respected when installing. #933</li> </ul>"},{"location":"dev/changelog/#dependencies_8","title":"Dependencies","text":"<ul> <li>Switch from <code>pythonfinder</code> to <code>findpython</code> as the Python version finder. #930</li> </ul>"},{"location":"dev/changelog/#release-v1132-2022-02-20","title":"Release v1.13.2 (2022-02-20)","text":""},{"location":"dev/changelog/#bug-fixes_76","title":"Bug Fixes","text":"<ul> <li>Fix a regression issue that prereleases can't be installed if the version specifier of the requirement doesn't imply that. #920</li> </ul>"},{"location":"dev/changelog/#release-v1131-2022-02-18","title":"Release v1.13.1 (2022-02-18)","text":""},{"location":"dev/changelog/#bug-fixes_77","title":"Bug Fixes","text":"<ul> <li>Fix a bug that bad pip cache dir value breaks PDM's check update function. #922</li> <li>Fix a race condition in parallel installation by changing metadata to a lazy property.   This fixes a bug that incompatible wheels are installed unexpectedly. #924</li> </ul>"},{"location":"dev/changelog/#release-v1130post0-2022-02-18","title":"Release v1.13.0.post0 (2022-02-18)","text":""},{"location":"dev/changelog/#bug-fixes_78","title":"Bug Fixes","text":"<ul> <li>Fix a bug that incompatible platform-specific wheels are installed. #921</li> </ul>"},{"location":"dev/changelog/#release-v1130-2022-02-18","title":"Release v1.13.0 (2022-02-18)","text":""},{"location":"dev/changelog/#features-improvements_39","title":"Features &amp; Improvements","text":"<ul> <li>Support <code>pre_*</code> and <code>post_*</code> scripts for task composition. Pre- and Post- scripts for <code>init</code>, <code>build</code>, <code>install</code> and <code>lock</code> will be run if present. #789</li> <li>Support <code>--config/-c</code> option to specify another global configuration file. #883</li> <li>Packages with extras require no longer inherit the dependencies from the same package without extras. It is because the package without extras are returned as one of the dependencies. This change won't break the existing lock files nor dependency cache. #892</li> <li>Support version ranges in <code>[tool.pdm.overrides]</code> table. #909</li> <li>Rename config <code>use_venv</code> to <code>python.use_venv</code>;   rename config <code>feature.install_cache</code> to <code>install.cache</code>;   rename config <code>feature.install_cache_method</code> to <code>install.cache_method</code>;   rename config <code>parallel_install</code> to <code>install.parallel</code>. #914</li> </ul>"},{"location":"dev/changelog/#bug-fixes_79","title":"Bug Fixes","text":"<ul> <li>Fix a bug that file URLs or VCS URLs don't work in <code>[tool.pdm.overrides]</code> table. #861</li> <li>Fix a bug of identifier mismatch for URL requirements without an explicit name. #901</li> <li>No <code>requires-python</code> should be produced if ANY(<code>*</code>) is given. #917</li> <li>Fix a bug that <code>pdm.lock</code> gets created when <code>--dry-run</code> is passed to <code>pdm add</code>. #918</li> </ul>"},{"location":"dev/changelog/#improved-documentation_3","title":"Improved Documentation","text":"<ul> <li>The default editable backend becomes <code>path</code>. #904</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_8","title":"Removals and Deprecations","text":"<ul> <li>Stop auto-migrating projects from PDM 0.x format. #912</li> </ul>"},{"location":"dev/changelog/#refactor","title":"Refactor","text":"<ul> <li>Rename <code>ExtrasError</code> to <code>ExtrasWarning</code> for better understanding. Improve the warning message. #892</li> <li>Extract the environment related code from <code>Candidate</code> into a new class <code>PreparedCandidate</code>.   <code>Candidate</code> no longer holds an <code>Environment</code> instance. #920</li> </ul>"},{"location":"dev/changelog/#release-v1128-2022-02-06","title":"Release v1.12.8 (2022-02-06)","text":""},{"location":"dev/changelog/#features-improvements_40","title":"Features &amp; Improvements","text":"<ul> <li>Print the error and continue if a plugin fails to load. #878</li> </ul>"},{"location":"dev/changelog/#bug-fixes_80","title":"Bug Fixes","text":"<ul> <li>PDM now ignores configuration of uninstalled plugins. #872</li> <li>Fix the compatibility issue with <code>pip&gt;=22.0</code>. #875</li> </ul>"},{"location":"dev/changelog/#release-v1127-2022-01-31","title":"Release v1.12.7 (2022-01-31)","text":""},{"location":"dev/changelog/#features-improvements_41","title":"Features &amp; Improvements","text":"<ul> <li>If no command is given to <code>pdm run</code>, it will run the Python REPL. #856</li> </ul>"},{"location":"dev/changelog/#bug-fixes_81","title":"Bug Fixes","text":"<ul> <li>Fix the hash calculation when generating <code>direct_url.json</code> for a local pre-built wheel. #861</li> <li>PDM no longer migrates project meta silently. #867</li> </ul>"},{"location":"dev/changelog/#dependencies_9","title":"Dependencies","text":"<ul> <li>Pin <code>pip&lt;22.0</code>. #874</li> </ul>"},{"location":"dev/changelog/#miscellany_5","title":"Miscellany","text":"<ul> <li>Reduce the number of tests that require network, and mark the rest with <code>network</code> marker. #858</li> </ul>"},{"location":"dev/changelog/#release-v1126-2022-01-12","title":"Release v1.12.6 (2022-01-12)","text":""},{"location":"dev/changelog/#bug-fixes_82","title":"Bug Fixes","text":"<ul> <li>Fix a bug that cache dir isn't created. #843</li> </ul>"},{"location":"dev/changelog/#release-v1125-2022-01-11","title":"Release v1.12.5 (2022-01-11)","text":""},{"location":"dev/changelog/#bug-fixes_83","title":"Bug Fixes","text":"<ul> <li>Fix a resolution error that dots in the package name are normalized to <code>-</code> unexpectedly. #853</li> </ul>"},{"location":"dev/changelog/#release-v1124-2022-01-11","title":"Release v1.12.4 (2022-01-11)","text":""},{"location":"dev/changelog/#features-improvements_42","title":"Features &amp; Improvements","text":"<ul> <li>Remember the last selection in <code>use</code> command to save the human effort.   And introduce an <code>-i</code> option to ignored that remembered value. #846</li> </ul>"},{"location":"dev/changelog/#bug-fixes_84","title":"Bug Fixes","text":"<ul> <li>Fix a bug of uninstall crash when the package has directories in <code>RECORD</code>. #847</li> <li>Fix the <code>ModuleNotFoundError</code> during uninstall when the modules required are removed. #850</li> </ul>"},{"location":"dev/changelog/#release-v1123-2022-01-07","title":"Release v1.12.3 (2022-01-07)","text":""},{"location":"dev/changelog/#features-improvements_43","title":"Features &amp; Improvements","text":"<ul> <li>Support setting Python path in global configuration. #842</li> </ul>"},{"location":"dev/changelog/#bug-fixes_85","title":"Bug Fixes","text":"<ul> <li>Lowercase the package names in the lock file make it more stable. #836</li> <li>Show the packages to be updated in dry run mode of <code>pdm update</code> even if <code>--no-sync</code> is passed. #837</li> <li>Improve the robustness of update check code. #841</li> <li>Fix a bug that export result has environment markers that don't apply for all requirements. #843</li> </ul>"},{"location":"dev/changelog/#release-v1122-2021-12-30","title":"Release v1.12.2 (2021-12-30)","text":""},{"location":"dev/changelog/#features-improvements_44","title":"Features &amp; Improvements","text":"<ul> <li>Allow changing the installation linking method by <code>feature.install_cache_method</code> config. #822</li> </ul>"},{"location":"dev/changelog/#bug-fixes_86","title":"Bug Fixes","text":"<ul> <li>Fix a bug that namespace packages can't be symlinked to the cache due to existing links. #820</li> <li>Make PDM generated pth files processed as early as possible. #821</li> <li>Fix a UnicodeDecodeError for subprocess logger under Windows/GBK. #823</li> </ul>"},{"location":"dev/changelog/#release-v1121-2021-12-24","title":"Release v1.12.1 (2021-12-24)","text":""},{"location":"dev/changelog/#bug-fixes_87","title":"Bug Fixes","text":"<ul> <li>Don't symlink pycaches to the target place. #817</li> </ul>"},{"location":"dev/changelog/#release-v1120-2021-12-22","title":"Release v1.12.0 (2021-12-22)","text":""},{"location":"dev/changelog/#features-improvements_45","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>lock --refresh</code> to update the hash stored with the lock file without updating the pinned versions. #642</li> <li>Support resolution overriding in the <code>[tool.pdm.overrides]</code> table. #790</li> <li>Add support for signals for basic operations, now including <code>post_init</code>, <code>pre_lock</code>, <code>post_lock</code>, <code>pre_install</code> and <code>post_install</code>. #798</li> <li>Add <code>install --check</code> to check if the lock file is up to date. #810</li> <li>Use symlinks to cache installed packages when it is supported by the file system. #814</li> </ul>"},{"location":"dev/changelog/#bug-fixes_88","title":"Bug Fixes","text":"<ul> <li>Fix a bug that candidates from urls are rejected by the <code>allow_prereleases</code> setting.   Now non-named requirements are resolved earlier than pinned requirements. #799</li> </ul>"},{"location":"dev/changelog/#improved-documentation_4","title":"Improved Documentation","text":"<ul> <li>Add a new doc page: API reference. #802</li> </ul>"},{"location":"dev/changelog/#dependencies_10","title":"Dependencies","text":"<ul> <li>Switch back from <code>atoml</code> to <code>tomlkit</code> as the style-preserving TOML parser. The latter has supported TOML v1.0.0. #809</li> </ul>"},{"location":"dev/changelog/#miscellany_6","title":"Miscellany","text":"<ul> <li>Cache the latest version of PDM for one week to reduce the request frequency. #800</li> </ul>"},{"location":"dev/changelog/#release-v1113-2021-12-15","title":"Release v1.11.3 (2021-12-15)","text":""},{"location":"dev/changelog/#features-improvements_46","title":"Features &amp; Improvements","text":"<ul> <li>Change the default version save strategy to <code>minimum</code>, without upper bounds. #787</li> </ul>"},{"location":"dev/changelog/#bug-fixes_89","title":"Bug Fixes","text":"<ul> <li>Fix the patching of sysconfig in PEP 582 initialization script. #796</li> </ul>"},{"location":"dev/changelog/#miscellany_7","title":"Miscellany","text":"<ul> <li>Fix an installation failure of the bootstrap script on macOS Catalina. #793</li> <li>Add a basic benchmarking script. #794</li> </ul>"},{"location":"dev/changelog/#release-v1112-2021-12-10","title":"Release v1.11.2 (2021-12-10)","text":""},{"location":"dev/changelog/#bug-fixes_90","title":"Bug Fixes","text":"<ul> <li>Fix the resolution order to reduce the loop number to find a conflict. #781</li> <li>Patch the functions in <code>sysconfig</code> to return the PEP 582 scheme in <code>pdm run</code>. #784</li> </ul>"},{"location":"dev/changelog/#dependencies_11","title":"Dependencies","text":"<ul> <li>Remove the upper bound of version constraints for most dependencies, except for some zero-versioned ones. #787</li> </ul>"},{"location":"dev/changelog/#release-v1111-2021-12-08","title":"Release v1.11.1 (2021-12-08)","text":""},{"location":"dev/changelog/#features-improvements_47","title":"Features &amp; Improvements","text":"<ul> <li>Support <code>--pre/--prelease</code> option for <code>pdm add</code> and <code>pdm update</code>. It will allow prereleases to be pinned. #774</li> <li>Improve the error message when python is found but not meeting the python requirement. #777</li> </ul>"},{"location":"dev/changelog/#bug-fixes_91","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>git+https</code> candidates cannot be resolved. #771</li> <li>Fix an infinite resolution loop by resolving the top-level packages first. Also deduplicate the lines from the same requirement in the error output. #776</li> </ul>"},{"location":"dev/changelog/#miscellany_8","title":"Miscellany","text":"<ul> <li>Fix the install script to use a zipapp of virtualenv when it isn't installed. #780</li> </ul>"},{"location":"dev/changelog/#release-v1110-2021-11-30","title":"Release v1.11.0 (2021-11-30)","text":""},{"location":"dev/changelog/#features-improvements_48","title":"Features &amp; Improvements","text":"<ul> <li>Move <code>version</code> from <code>[project]</code> table to <code>[tool.pdm]</code> table, delete <code>classifiers</code> from <code>dynamic</code>, and warn usage about the deprecated usages. #748</li> <li>Add support for Conda environments in addition to Python virtual environments. #749</li> <li>Add support for saving only the lower bound <code>x &gt;= VERSION</code> when adding dependencies. #752</li> <li>Improve the error message when resolution fails. #754</li> </ul>"},{"location":"dev/changelog/#bug-fixes_92","title":"Bug Fixes","text":"<ul> <li>Switch to self-implemented <code>pdm list --freeze</code> to fix a bug due to Pip's API change. #533</li> <li>Fix an infinite loop issue when resolving candidates with incompatible <code>requires-python</code>. #744</li> <li>Fix the python finder to support pyenv-win. #745</li> <li>Fix the ANSI color output for Windows cmd and Powershell terminals. #753</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_9","title":"Removals and Deprecations","text":"<ul> <li>Remove <code>-s/--section</code> option from all previously supported commands. Use <code>-G/--group</code> instead. #756</li> </ul>"},{"location":"dev/changelog/#release-v1103-2021-11-18","title":"Release v1.10.3 (2021-11-18)","text":""},{"location":"dev/changelog/#bug-fixes_93","title":"Bug Fixes","text":"<ul> <li>Use <code>importlib</code> to replace <code>imp</code> in the <code>sitecustomize</code> module for Python 3. #574</li> <li>Fix the lib paths under non-isolated build. #740</li> <li>Exclude the dependencies with extras in the result of <code>pdm export</code>. #741</li> </ul>"},{"location":"dev/changelog/#release-v1102-2021-11-14","title":"Release v1.10.2 (2021-11-14)","text":""},{"location":"dev/changelog/#features-improvements_49","title":"Features &amp; Improvements","text":"<ul> <li>Add a new option <code>-s/--site-packages</code> to <code>pdm run</code> as well as a script config item. When it is set to <code>True</code>, site-packages from the selected interpreter will be loaded into the running environment. #733</li> </ul>"},{"location":"dev/changelog/#bug-fixes_94","title":"Bug Fixes","text":"<ul> <li>Now <code>NO_SITE_PACKAGES</code> isn't set in <code>pdm run</code> if the executable is out of local packages. #733</li> </ul>"},{"location":"dev/changelog/#release-v1101-2021-11-09","title":"Release v1.10.1 (2021-11-09)","text":""},{"location":"dev/changelog/#features-improvements_50","title":"Features &amp; Improvements","text":"<ul> <li>Isolate the project environment with system site packages in <code>pdm run</code>, but keep them seen when PEP 582 is enabled. #708</li> </ul>"},{"location":"dev/changelog/#bug-fixes_95","title":"Bug Fixes","text":"<ul> <li>Run <code>pip</code> with <code>--isolated</code> when building wheels. In this way some env vars like <code>PIP_REQUIRE_VIRTUALENV</code> can be ignored. #669</li> <li>Fix the install script to ensure <code>pip</code> is not DEBUNDLED. #685</li> <li>Fix a bug that when <code>summary</code> is <code>None</code>, the lockfile can't be generated. #719</li> <li><code>${PROJECT_ROOT}</code> should be written in the URL when relative path is given. #721</li> <li>Fix a bug that when project table already exists, <code>pdm import</code> can't merge the settings correctly. #723</li> </ul>"},{"location":"dev/changelog/#release-v1100-2021-10-25","title":"Release v1.10.0 (2021-10-25)","text":""},{"location":"dev/changelog/#features-improvements_51","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>--no-sync</code> option to <code>update</code> command. #684</li> <li>Support <code>find_links</code> source type. It can be specified via <code>type</code> key of <code>[[tool.pdm.source]]</code> table. #694</li> <li>Add <code>--dry-run</code> option to <code>add</code>, <code>install</code> and <code>remove</code> commands. #698</li> </ul>"},{"location":"dev/changelog/#bug-fixes_96","title":"Bug Fixes","text":"<ul> <li>Remove trailing whitespace with terminal output of tables (via <code>project.core.ui.display_columns</code>), fixing unnecessary wrapping due to / with empty lines full of spaces in case of long URLs in the last column. #680</li> <li>Include files should be installed under venv's base path. #682</li> <li>Ensure the value of <code>check_update</code> is boolean. #689</li> </ul>"},{"location":"dev/changelog/#improved-documentation_5","title":"Improved Documentation","text":"<ul> <li>Update the contributing guide, remove the usage of <code>setup_dev.py</code> in favor of <code>pip install</code>. #676</li> </ul>"},{"location":"dev/changelog/#release-v190-2021-10-12","title":"Release v1.9.0 (2021-10-12)","text":""},{"location":"dev/changelog/#bug-fixes_97","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>requires-python</code> is not recognized in candidates evaluation. #657</li> <li>Fix the path order when pdm run so that executables in local packages dir are found first. #678</li> </ul>"},{"location":"dev/changelog/#dependencies_12","title":"Dependencies","text":"<ul> <li>Update <code>installer</code> to <code>0.3.0</code>, fixing a bug that broke installation of some packages with unusual wheel files. #653</li> <li>Change <code>packaging</code> and <code>typing-extensions</code> to direct dependencies. #674</li> </ul>"},{"location":"dev/changelog/#refactor_1","title":"Refactor","text":"<ul> <li><code>requires-python</code> now participates in the resolution as a dummy requirement. #658</li> </ul>"},{"location":"dev/changelog/#release-v185-2021-09-16","title":"Release v1.8.5 (2021-09-16)","text":""},{"location":"dev/changelog/#bug-fixes_98","title":"Bug Fixes","text":"<ul> <li>Fix the error of regex to find the shebang line. #656</li> </ul>"},{"location":"dev/changelog/#release-v184-2021-09-15","title":"Release v1.8.4 (2021-09-15)","text":""},{"location":"dev/changelog/#features-improvements_52","title":"Features &amp; Improvements","text":"<ul> <li>Support <code>--no-isolation</code> option for <code>install</code>, <code>lock</code>, <code>update</code>, <code>remove</code>, <code>sync</code> commands. #640</li> <li>Make <code>project_max_depth</code> configurable and default to <code>5</code>. #643</li> </ul>"},{"location":"dev/changelog/#bug-fixes_99","title":"Bug Fixes","text":"<ul> <li>Don't try <code>pdm-pep517</code> backend on Python 2.7 when installing self as editable. #640</li> <li>Fix a bug that existing shebang can't be replaced correctly. #651</li> <li>Fix the version range saving for prerelease versions. #654</li> </ul>"},{"location":"dev/changelog/#release-v183-2021-09-07","title":"Release v1.8.3 (2021-09-07)","text":""},{"location":"dev/changelog/#features-improvements_53","title":"Features &amp; Improvements","text":"<ul> <li>Allow to build in non-isolated environment, to enable optional speedups depending on the environment. #635</li> </ul>"},{"location":"dev/changelog/#bug-fixes_100","title":"Bug Fixes","text":"<ul> <li>Don't copy <code>*-nspkg.pth</code> files in <code>install_cache</code> mode. It will still work without them. #623</li> </ul>"},{"location":"dev/changelog/#release-v182-2021-09-01","title":"Release v1.8.2 (2021-09-01)","text":""},{"location":"dev/changelog/#bug-fixes_101","title":"Bug Fixes","text":"<ul> <li>Fix the removal issue of standalone pyc files #633</li> </ul>"},{"location":"dev/changelog/#release-v181-2021-08-26","title":"Release v1.8.1 (2021-08-26)","text":""},{"location":"dev/changelog/#features-improvements_54","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>-r/--reinstall</code> option to <code>sync</code> command to force re-install the existing dependencies. #601</li> <li>Show update hint after every pdm command. #603</li> <li><code>pdm cache clear</code> can clear cached installations if not needed any more. #604</li> </ul>"},{"location":"dev/changelog/#bug-fixes_102","title":"Bug Fixes","text":"<ul> <li>Fix the editable install script so that <code>setuptools</code> won't see the dependencies under local packages. #601</li> <li>Preserve the executable bit when installing wheels. #606</li> <li>Write PEP 610 metadata <code>direct_url.json</code> when installing wheels. #607</li> <li>Fix a bug that <code>*</code> fails to be converted as <code>SpecifierSet</code>. #609</li> </ul>"},{"location":"dev/changelog/#refactor_2","title":"Refactor","text":"<ul> <li>Build editable packages are into wheels via PEP 660 build backend. Now all installations are unified into wheels. #612</li> </ul>"},{"location":"dev/changelog/#release-v180-2021-08-16","title":"Release v1.8.0 (2021-08-16)","text":""},{"location":"dev/changelog/#features-improvements_55","title":"Features &amp; Improvements","text":"<ul> <li>Added a new mode <code>--json</code> to the list command which outputs the dependency graph as a JSON document. #583</li> <li>Add a new config <code>feature.install_cache</code>. When it is turned on, wheels will be installed into a centralized package repo and create <code>.pth</code> files under project packages directory to link to the cached package. #589</li> </ul>"},{"location":"dev/changelog/#bug-fixes_103","title":"Bug Fixes","text":"<ul> <li>Fix env vars in source URLs not being expanded in all cases. #570</li> <li>Fix the weird output of <code>pdm show</code>. #580</li> <li>Prefer <code>~/.pyenv/shims/python3</code> as the pyenv interpreter. #590</li> <li>Fix a bug that installing will download candidates that do not match the locked hashes. #596</li> </ul>"},{"location":"dev/changelog/#improved-documentation_6","title":"Improved Documentation","text":"<ul> <li>Added instructions to the Contributing section for creating news fragments #573</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_10","title":"Removals and Deprecations","text":"<ul> <li>Deprecate <code>-s/--section</code> option in favor of <code>-G/--group</code>. #591</li> </ul>"},{"location":"dev/changelog/#refactor_3","title":"Refactor","text":"<ul> <li>Switch to a self-implemented version of uninstaller. #586</li> <li><code>pdm/installers/installers.py</code> is renamed to <code>pdm/installers/manager.py</code> to be more accurate. The <code>Installer</code> class under that file is renamed to <code>InstallerManager</code> and is exposed in the <code>pdm.core.Core</code> object for overriding. The new <code>pdm/installers/installers.py</code> contains some installation implementations. #589</li> <li>Switch from <code>pkg_resources.Distribution</code> to the implementation of <code>importlib.metadata</code>. #592</li> </ul>"},{"location":"dev/changelog/#release-v172-2021-07-30","title":"Release v1.7.2 (2021-07-30)","text":""},{"location":"dev/changelog/#bug-fixes_104","title":"Bug Fixes","text":"<ul> <li>Remove the existing files before installing. #565</li> <li>Deduplicate the plugins list. #566</li> </ul>"},{"location":"dev/changelog/#release-v171-2021-07-29","title":"Release v1.7.1 (2021-07-29)","text":""},{"location":"dev/changelog/#bug-fixes_105","title":"Bug Fixes","text":"<ul> <li>Accept non-canonical distribution name in the wheel's dist-info directory name. #529</li> <li>Prefer requirements with narrower version constraints or allowing prereleases to find matches. #551</li> <li>Use the underlying real executable path for writing shebangs. #553</li> <li>Fix a bug that extra markers cannot be extracted when combined with other markers with \"and\". #559</li> <li>Fix a bug that redacted credentials in source urls get overwritten with the plain text after locking. #561</li> </ul>"},{"location":"dev/changelog/#refactor_4","title":"Refactor","text":"<ul> <li>Use installer as the wheel installer, replacing <code>distlib</code>. #519</li> </ul>"},{"location":"dev/changelog/#release-v170-2021-07-20","title":"Release v1.7.0 (2021-07-20)","text":""},{"location":"dev/changelog/#features-improvements_56","title":"Features &amp; Improvements","text":"<ul> <li>Support showing individual fields by <code>--&lt;field-name&gt;</code> options in pdm show. When no package is given, show this project. #527</li> <li>Add <code>--freeze</code> option to <code>pdm list</code> command which shows the dependencies list as pip's requirements.txt format. #531</li> </ul>"},{"location":"dev/changelog/#bug-fixes_106","title":"Bug Fixes","text":"<ul> <li>Fix the path manipulation on Windows, now the PEP 582 path is prepended to the <code>PYTHONPATH</code>. #522</li> <li>Fix the handling of auth prompting: will try keyring in non-verbose mode. #523</li> <li>Recognize old entry point name \"pdm.plugin\" for backward-compatibility. #530</li> <li>Match the VCS scheme in case-insensitive manner. #537</li> <li>Use the default permission bits when writing project files. #542</li> <li>Fix the VCS url to be consistent between lock and install. #547</li> </ul>"},{"location":"dev/changelog/#improved-documentation_7","title":"Improved Documentation","text":"<ul> <li>Add installation instructions for Scoop. #522</li> </ul>"},{"location":"dev/changelog/#dependencies_13","title":"Dependencies","text":"<ul> <li>Update <code>pdm-pep517</code> to <code>0.8.0</code>. #524</li> <li>Switch from <code>toml</code> to <code>tomli</code>. #541</li> </ul>"},{"location":"dev/changelog/#refactor_5","title":"Refactor","text":"<ul> <li>Separate the build env into two different levels for better caching. #541</li> <li>Refactor the build part into smaller functions. #543</li> </ul>"},{"location":"dev/changelog/#release-v164-2021-06-23","title":"Release v1.6.4 (2021-06-23)","text":""},{"location":"dev/changelog/#features-improvements_57","title":"Features &amp; Improvements","text":"<ul> <li>Extract package name from egg-info in filename when eligible. Remove the patching code of resolvelib's inner class. #441</li> <li>Support installing packages from subdiretories of VCS repository. #507</li> <li>Add an install script to bootstrap PDM quickly without help of other tools. Modify docs to recommend this installation method. #508</li> <li>Add a new subcommand <code>plugin</code> to manage pdm plugins, including <code>add</code>, <code>remove</code> and <code>list</code> commands. #510</li> </ul>"},{"location":"dev/changelog/#bug-fixes_107","title":"Bug Fixes","text":"<ul> <li>Don't monkeypatch the internal class of <code>resolvelib</code> any more. This makes PDM more stable across updates of sub-dependencies. #515</li> </ul>"},{"location":"dev/changelog/#miscellany_9","title":"Miscellany","text":"<ul> <li>Clear the type errors from mypy. #261</li> </ul>"},{"location":"dev/changelog/#release-v163-2021-06-17","title":"Release v1.6.3 (2021-06-17)","text":""},{"location":"dev/changelog/#features-improvements_58","title":"Features &amp; Improvements","text":"<ul> <li>Add an option <code>-u/--unconstrained</code> to support unconstraining version specifiers when adding packages. #501</li> </ul>"},{"location":"dev/changelog/#bug-fixes_108","title":"Bug Fixes","text":"<ul> <li>Fix the format of dependency arrays when a new value is appended. #487</li> <li>Allow missing email attribute for authors and maintainers. #492</li> <li>Fix a bug that editable install shouldn't require pyproject.toml to be valid. #497</li> <li>Fix a bug on macOS that purelib and platlib paths of isolated build envs cannot be substituted correctly if the Python is a framework build. #502</li> <li>Fix the version sort of candidates. #506</li> </ul>"},{"location":"dev/changelog/#release-v162-2021-05-31","title":"Release v1.6.2 (2021-05-31)","text":"<p>No significant changes.</p>"},{"location":"dev/changelog/#release-v161-2021-05-31","title":"Release v1.6.1 (2021-05-31)","text":"<p>No significant changes.</p>"},{"location":"dev/changelog/#release-v160-2021-05-31","title":"Release v1.6.0 (2021-05-31)","text":""},{"location":"dev/changelog/#features-improvements_59","title":"Features &amp; Improvements","text":"<ul> <li>Use a new approach to determine the packages to be installed. This requires a quick resolution step before installation. #456</li> <li><code>pdm export</code> no longer produces requirements file applicable for all platforms due to the new approach. #456</li> <li>Add structural typing for requirements module. Refactor the requirements module for that purpose. #433</li> <li>Introduce <code>--no-editable</code> option to install non-editable versions of all packages. #443</li> <li>Introduce <code>--no-self</code> option to prevent the project itself from being installed. #444</li> <li>Add a default <code>.gitignore</code> file in the <code>__pypackages__</code> directory. #446</li> <li>Check if the lock file version is compatible with PDM program before installation. #463</li> <li>Expose the project root path via <code>PDM_PROJECT_ROOT</code> env var. Change to the project root when executing scripts. #470</li> <li>Fix a bug that installation resolution doesn't respect the requirement markers from pyproject config. #480</li> </ul>"},{"location":"dev/changelog/#bug-fixes_109","title":"Bug Fixes","text":"<ul> <li>Changing to multiline breaks the parsing of TOML document. #462</li> <li>Fix a bug that transient dependencies of conditional requirements can't be resolved. #472</li> <li>Fix a bug that invalid wheels are rejected while they are acceptable for resolution. #473</li> <li>Fix a bug that build environment is not fully isolated with the hosted environment. #477</li> <li>Ensure the lock file is compatible before looking for the locked candidates. #484</li> </ul>"},{"location":"dev/changelog/#improved-documentation_8","title":"Improved Documentation","text":"<ul> <li>Fix 404 links in documentation. #472</li> </ul>"},{"location":"dev/changelog/#dependencies_14","title":"Dependencies","text":"<ul> <li>Migrate from <code>tomlkit</code> to <code>atoml</code> as the style-preserving TOML parser and writer. #465</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_11","title":"Removals and Deprecations","text":"<ul> <li>Remove the warning of <code>--dev</code> flag for older versions of PDM. #444</li> </ul>"},{"location":"dev/changelog/#miscellany_10","title":"Miscellany","text":"<ul> <li>Add Python 3.10 beta CI job. #457</li> </ul>"},{"location":"dev/changelog/#release-v153-2021-05-10","title":"Release v1.5.3 (2021-05-10)","text":""},{"location":"dev/changelog/#features-improvements_60","title":"Features &amp; Improvements","text":"<ul> <li>Support passing options to the build backends via <code>--config-setting</code>. #452</li> </ul>"},{"location":"dev/changelog/#bug-fixes_110","title":"Bug Fixes","text":"<ul> <li>Seek for other sitecustomize.py to import. #422</li> <li>Fix an unescaped single quote in fish completion script. #423</li> <li>The hashes of a remote file candidate should be calculated from the link itself. #450</li> </ul>"},{"location":"dev/changelog/#dependencies_15","title":"Dependencies","text":"<ul> <li>Remove <code>keyring</code> as a dependency and guide users to install it when it is not available. #442</li> <li>Specify the minimum version of <code>distlib</code>. #447</li> </ul>"},{"location":"dev/changelog/#miscellany_11","title":"Miscellany","text":"<ul> <li>Add log output about found candidates and their origin. #421</li> <li>Add mypy pre-commit hook #427</li> <li>Improve type safety of <code>pdm.cli.actions</code> #428</li> <li>Fix wrong mypy configuration. #451</li> </ul>"},{"location":"dev/changelog/#release-v152-2021-04-27","title":"Release v1.5.2 (2021-04-27)","text":""},{"location":"dev/changelog/#features-improvements_61","title":"Features &amp; Improvements","text":"<ul> <li>Allow <code>pdm use</code> with no argument given, which will list all available pythons for pick. #409</li> </ul>"},{"location":"dev/changelog/#bug-fixes_111","title":"Bug Fixes","text":"<ul> <li>Inform user to enable PEP 582 for development script to work. #404</li> <li>Check the existence of pyenv shim Python interpreter before using it. #406</li> <li>Fix a bug that executing <code>setup.py</code> failed for NameError. #407</li> <li>Check before setting the PYTHONPATH environment variable for PEP582 #410</li> <li>Fix development setup error. #415</li> </ul>"},{"location":"dev/changelog/#dependencies_16","title":"Dependencies","text":"<ul> <li>Update pip to 21.1 and fix compatibility issues. #412</li> </ul>"},{"location":"dev/changelog/#release-v151-2021-04-22","title":"Release v1.5.1 (2021-04-22)","text":""},{"location":"dev/changelog/#bug-fixes_112","title":"Bug Fixes","text":"<ul> <li>Make func translate_sections pure to avoid exporting requirements in random order. #401</li> <li>Expand the variables in install requirements' attributes for build. #402</li> </ul>"},{"location":"dev/changelog/#release-v150-2021-04-20","title":"Release v1.5.0 (2021-04-20)","text":""},{"location":"dev/changelog/#features-improvements_62","title":"Features &amp; Improvements","text":"<ul> <li>Include dev dependencies by default for <code>install</code> and <code>sync</code> commands. Add a new option <code>--prod/--production</code> to exclude them. Improve the dependency selection logic to be more convenient to use \u2014 the more common the usage is, the shorter the command is. #391</li> </ul>"},{"location":"dev/changelog/#bug-fixes_113","title":"Bug Fixes","text":"<ul> <li>Enquote executable path to ensure generating valid scripts. #387</li> <li>Consider hashes when fetching artifact link for build. #389</li> <li>Considier the sources settings when building. #399</li> </ul>"},{"location":"dev/changelog/#improved-documentation_9","title":"Improved Documentation","text":"<ul> <li>New pdm setting <code>source-includes</code> to mark files to be included only in sdist builds. #390</li> </ul>"},{"location":"dev/changelog/#dependencies_17","title":"Dependencies","text":"<ul> <li>Update <code>pdm-pep517</code> to <code>0.7.0</code>; update <code>resolvelib</code> to<code>0.7.0</code>. #390</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_12","title":"Removals and Deprecations","text":"<ul> <li>Deprecate the usage of <code>-d/--dev</code> option in <code>install</code> and <code>sync</code> commands. #391</li> </ul>"},{"location":"dev/changelog/#release-v150b1-2021-04-12","title":"Release v1.5.0b1 (2021-04-12)","text":""},{"location":"dev/changelog/#features-improvements_63","title":"Features &amp; Improvements","text":"<ul> <li>Improve the env builder to run in isolated mode. #384</li> </ul>"},{"location":"dev/changelog/#bug-fixes_114","title":"Bug Fixes","text":"<ul> <li>Remove the incompatible code from the files that will be run in-process. #375</li> <li>Get the correct Python ABI tag of selected interpreter #378</li> <li>Error out when doing <code>pdm run</code> on a directory not initialized yet.</li> <li>Give warning message when the project automatically fallbacks to the global project.</li> </ul>"},{"location":"dev/changelog/#dependencies_18","title":"Dependencies","text":"<ul> <li>Upgrade <code>resolvelib</code> to <code>0.6.0</code>. #381</li> </ul>"},{"location":"dev/changelog/#miscellany_12","title":"Miscellany","text":"<ul> <li>refactor <code>pdm.models.readers</code> to improve typing support #321</li> <li>Add a basic integration test for cross-python check. #377</li> <li>Refactor the <code>project.python_executable</code> to <code>project.python</code> that contains all info of the interpreter. #382</li> <li>Continue refactoring Python info to extract to its own module. #383</li> <li>Refactor the creation of project.</li> </ul>"},{"location":"dev/changelog/#release-v150b0-2021-04-03","title":"Release v1.5.0b0 (2021-04-03)","text":""},{"location":"dev/changelog/#features-improvements_64","title":"Features &amp; Improvements","text":"<ul> <li>Add hand-written zsh completion script. #188</li> <li>Add a special value <code>:all</code> given to <code>-s/--section</code> to refer to all sections under the same species.   Adjust <code>add</code>, <code>sync</code>, <code>install</code>, <code>remove</code> and <code>update</code> to support the new <code>dev-dependencies</code> groups. Old behavior will be kept the same. #351</li> <li><code>dev-dependencies</code> is now a table of dependencies groups, where key is the group name and value is an array of dependencies. These dependencies won't appear in the distribution's metadata. <code>dev-depedencies</code> of the old format will turn into <code>dev</code> group under <code>dev-dependencies</code>. #351</li> <li>Move <code>dev-dependencies</code>, <code>includes</code>, <code>excludes</code> and <code>package-dir</code> out from <code>[project]</code> table to <code>[tool.pdm]</code> table. The migration will be done automatically if old format is detected. #351</li> <li>Throws an error with meaningful message when no candidate is found for one requirement. #357</li> <li>Support <code>--dry-run</code> option for <code>update</code> command to display packages that need update, install or removal. Add <code>--top</code> option to limit to top level packages only. #358</li> <li>Full-featured completion scripts for Zsh and Powershell - section selection, package name autocompletion and so on. Windows is a first-class citizen! #367</li> <li>Support non-interactive <code>init</code> command via <code>-n/--non-interactive</code> option. No question will be asked in this mode. #368</li> <li>Show project packages path(PEP 582) in the output of <code>pdm info</code>, also add an option <code>--packages</code> to show that value only. #372</li> </ul>"},{"location":"dev/changelog/#bug-fixes_115","title":"Bug Fixes","text":"<ul> <li>Fix a bug that pure python libraries are not loaded to construct the WorkingSet. #346</li> <li>Don't write <code>&lt;script&gt;-X.Y</code> variant to the bin folder. #365</li> <li>Python is now run in isolated mode via subprocess to avoid accidentally importing user packages. #369</li> <li>Don't overwrite existing dependencies when importing from requirements.txt. #370</li> </ul>"},{"location":"dev/changelog/#improved-documentation_10","title":"Improved Documentation","text":"<ul> <li>Add instructions of how to integrate PDM with Emacs, contributed by @linw1995. #372</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_13","title":"Removals and Deprecations","text":"<ul> <li>Remove the support of project path following <code>-g/--global</code> that was deprecated in <code>1.4.0</code>. One should use <code>-g -p &lt;project_path&gt;</code> for that purpose. #361</li> </ul>"},{"location":"dev/changelog/#miscellany_13","title":"Miscellany","text":"<ul> <li>Add test coverage to PDM. #109</li> <li>Add type annotations into untyped functions to start using mypy. #354</li> <li>Refactor the format converter code to be more explicit. #360</li> </ul>"},{"location":"dev/changelog/#release-v145-2021-03-30","title":"Release v1.4.5 (2021-03-30)","text":""},{"location":"dev/changelog/#features-improvements_65","title":"Features &amp; Improvements","text":"<ul> <li>Skip the first prompt of <code>pdm init</code> #352</li> </ul>"},{"location":"dev/changelog/#bug-fixes_116","title":"Bug Fixes","text":"<ul> <li>Fix a test failure when using homebrew installed python. #348</li> <li>Get revision from the VCS URL if source code isn't downloaded to local. #349</li> </ul>"},{"location":"dev/changelog/#dependencies_19","title":"Dependencies","text":"<ul> <li>Update dependency <code>pdm-pep517</code> to <code>0.6.1</code>. #353</li> </ul>"},{"location":"dev/changelog/#release-v144-2021-03-27","title":"Release v1.4.4 (2021-03-27)","text":""},{"location":"dev/changelog/#features-improvements_66","title":"Features &amp; Improvements","text":"<ul> <li>Emit warning if version or description can't be retrieved when importing from flit metadata. #342</li> <li>Add <code>type</code> argument to <code>pdm cache clear</code> and improve its UI. #343</li> <li>Always re-install the editable packages when syncing the working set. This can help tracking the latest change of <code>entry-points</code>. #344</li> </ul>"},{"location":"dev/changelog/#bug-fixes_117","title":"Bug Fixes","text":"<ul> <li>Make installer quit early if a wheel isn't able to build. #338</li> </ul>"},{"location":"dev/changelog/#miscellany_14","title":"Miscellany","text":"<ul> <li>ignore type checking in <code>models.project_info.ProjectInfo</code>, which indexes <code>distlib.metadata._data</code> #335</li> </ul>"},{"location":"dev/changelog/#release-v143-2021-03-24","title":"Release v1.4.3 (2021-03-24)","text":""},{"location":"dev/changelog/#features-improvements_67","title":"Features &amp; Improvements","text":"<ul> <li>Change the group name of entry points from <code>pdm.plugins</code> to <code>pdm</code>.   Export some useful objects and models for shorter import path. #318</li> <li>Field <code>cmd</code> in <code>tools.pdm.scripts</code> configuration items now allows specifying an argument array instead of a string.</li> <li>Refactor: Remove the reference of <code>stream</code> singleton, improve the UI related code. #320</li> <li>Support dependencies managed by poetry and flit being installed as editable packages. #324</li> <li>Refactor: Extract the logic of finding interpreters to method for the sake of subclass overriding. #326</li> <li>Complete the <code>cache</code> command, add <code>list</code>, <code>remove</code> and <code>info</code> subcommands. #329</li> <li>Refactor: Unify the code about selecting interpreter to reduce the duplication. #331</li> <li>Retrieve the version and description of a flit project by parsing the AST of the main file. #333</li> </ul>"},{"location":"dev/changelog/#bug-fixes_118","title":"Bug Fixes","text":"<ul> <li>Fix a parsing error when non-ascii characters exist in <code>pyproject.toml</code>. #308</li> <li>Fix a bug that non-editable VCS candidates can't satisfy their requirements once locked in the lock file. #314</li> <li>Fix a bug of import-on-init that fails when requirements.txt is detected. #328</li> </ul>"},{"location":"dev/changelog/#miscellany_15","title":"Miscellany","text":"<ul> <li>refactor <code>pdm.iostream</code> to improve 'typing' support #301</li> <li>fix some typos #323</li> </ul>"},{"location":"dev/changelog/#release-v142-2021-03-18","title":"Release v1.4.2 (2021-03-18)","text":""},{"location":"dev/changelog/#features-improvements_68","title":"Features &amp; Improvements","text":"<ul> <li>Refactor the code, extract the version related logic from <code>specifiers.py</code> to a separated module. #303</li> </ul>"},{"location":"dev/changelog/#bug-fixes_119","title":"Bug Fixes","text":"<ul> <li>Fix a bug that get_dependencies() returns error when the <code>setup.py</code> has no <code>intall_requires</code> key. #299</li> <li>Pin the VCS revision for non-editable VCS candidates in the lock file. #305</li> <li>Fix a bug that editable build hits the cached wheel unexpectedly. #307</li> </ul>"},{"location":"dev/changelog/#miscellany_16","title":"Miscellany","text":"<ul> <li>replace 'typing comments' with type annotations throughout #298</li> </ul>"},{"location":"dev/changelog/#release-v141-2021-03-12","title":"Release v1.4.1 (2021-03-12)","text":""},{"location":"dev/changelog/#features-improvements_69","title":"Features &amp; Improvements","text":"<ul> <li>Support importing dependencies from requirements.txt to dev-dependencies or sections. #291</li> </ul>"},{"location":"dev/changelog/#bug-fixes_120","title":"Bug Fixes","text":"<ul> <li>Fallback to static parsing when building was failed to find the dependencies of a candidate. #293</li> <li>Fix a bug that <code>pdm init</code> fails when <code>pyproject.toml</code> exists but has no <code>[project]</code> section. #295</li> </ul>"},{"location":"dev/changelog/#improved-documentation_11","title":"Improved Documentation","text":"<ul> <li>Document about how to use PDM with Nox. #281</li> </ul>"},{"location":"dev/changelog/#release-v140-2021-03-05","title":"Release v1.4.0 (2021-03-05)","text":""},{"location":"dev/changelog/#features-improvements_70","title":"Features &amp; Improvements","text":"<ul> <li>When <code>-I/--ignore-python</code> passed or <code>PDM_IGNORE_SAVED_PYTHON=1</code>, ignore the interpreter set in <code>.pdm.toml</code> and don't save to it afterwards. #283</li> <li>A new option <code>-p/--project</code> is introduced to specify another path for the project base. It can also be combined with <code>-g/--global</code> option.   The latter is changed to a flag only option that does not accept values. #286</li> <li>Support <code>-f setuppy</code> for <code>pdm export</code> to export the metadata as setup.py #289</li> </ul>"},{"location":"dev/changelog/#bug-fixes_121","title":"Bug Fixes","text":"<ul> <li>Fix a bug that editable local package requirements cannot be parsed rightly. #285</li> <li>Change the priority of metadata files to parse so that PEP 621 metadata will be parsed first. #288</li> </ul>"},{"location":"dev/changelog/#improved-documentation_12","title":"Improved Documentation","text":"<ul> <li>Add examples of how to integrate with CI pipelines (and tox). #281</li> </ul>"},{"location":"dev/changelog/#release-v134-2021-03-01","title":"Release v1.3.4 (2021-03-01)","text":""},{"location":"dev/changelog/#improved-documentation_13","title":"Improved Documentation","text":"<ul> <li>added documentation on a task provider for vscode #280</li> </ul>"},{"location":"dev/changelog/#bug-fixes_122","title":"Bug Fixes","text":"<ul> <li>Ignore the python requires constraints when fetching the link from the PyPI index.</li> </ul>"},{"location":"dev/changelog/#release-v133-2021-02-26","title":"Release v1.3.3 (2021-02-26)","text":""},{"location":"dev/changelog/#bug-fixes_123","title":"Bug Fixes","text":"<ul> <li>Fix the requirement string of a VCS requirement to comply with PEP 508. #275</li> <li>Fix a bug that editable packages with <code>src</code> directory can't be uninstalled correctly. #277</li> <li>Fix a bug that editable package doesn't override the non-editable version in the working set. #278</li> </ul>"},{"location":"dev/changelog/#release-v132-2021-02-25","title":"Release v1.3.2 (2021-02-25)","text":""},{"location":"dev/changelog/#features-improvements_71","title":"Features &amp; Improvements","text":"<ul> <li>Abort and tell user the selected section following <code>pdm sync</code> or <code>pdm install</code> is not present in the error message. #274</li> </ul>"},{"location":"dev/changelog/#bug-fixes_124","title":"Bug Fixes","text":"<ul> <li>Fix a bug that candidates' sections cannot be retrieved rightly when circular dependencies exist. #270</li> <li>Don't pass the help argument into the run script method. #272</li> </ul>"},{"location":"dev/changelog/#release-v131-2021-02-19","title":"Release v1.3.1 (2021-02-19)","text":""},{"location":"dev/changelog/#bug-fixes_125","title":"Bug Fixes","text":"<ul> <li>Use the absolute path when importing from a Poetry pyproject.toml. #262</li> <li>Fix a bug that old toml table head is kept when converting to PEP 621 metadata format. #263</li> <li>Postpone the evaluation of <code>requires-python</code> attribute when fetching the candidates of a package. #264</li> </ul>"},{"location":"dev/changelog/#release-v130-2021-02-09","title":"Release v1.3.0 (2021-02-09)","text":""},{"location":"dev/changelog/#features-improvements_72","title":"Features &amp; Improvements","text":"<ul> <li>Increase the default value of the max rounds of resolution to 1000, make it configurable. #238</li> <li>Rewrite the project's <code>egg-info</code> directory when dependencies change. So that <code>pdm list --graph</code> won't show invalid entries. #240</li> <li>When importing requirements from a <code>requirements.txt</code> file, build the package to find the name if not given in the URL. #245</li> <li>When initializing the project, prompt user for whether the project is a library, and give empty <code>name</code> and <code>version</code> if not. #253</li> </ul>"},{"location":"dev/changelog/#bug-fixes_126","title":"Bug Fixes","text":"<ul> <li>Fix the version validator of wheel metadata to align with the implementation of <code>packaging</code>. #130</li> <li>Preserve the <code>sections</code> value of a pinned candidate to be reused. #234</li> <li>Strip spaces in user input when prompting for the python version to use. #252</li> <li>Fix the version parsing of Python requires to allow <code>&gt;</code>, <code>&gt;=</code>, <code>&lt;</code>, <code>&lt;=</code> to combine with star versions. #254</li> </ul>"},{"location":"dev/changelog/#release-v120-2021-01-26","title":"Release v1.2.0 (2021-01-26)","text":""},{"location":"dev/changelog/#features-improvements_73","title":"Features &amp; Improvements","text":"<ul> <li>Change the behavior of <code>--save-compatible</code> slightly. Now the version specifier saved is using the REAL compatible operator <code>~=</code> as described in PEP 440. Before: <code>requests&lt;3.0.0,&gt;=2.19.1</code>, After: <code>requests~=2.19</code>. The new specifier accepts <code>requests==2.19.0</code> as compatible version. #225</li> <li>Environment variable <code>${PROJECT_ROOT}</code> in the dependency specification can be expanded to refer to the project root in pyproject.toml.   The environment variables will be kept as they are in the lock file. #226</li> <li>Change the dependencies of a package in the lock file to a list of PEP 508 strings #236</li> </ul>"},{"location":"dev/changelog/#bug-fixes_127","title":"Bug Fixes","text":"<ul> <li>Ignore user's site and <code>PYTHONPATH</code>(with <code>python -I</code> mode) when executing pip commands. #231</li> </ul>"},{"location":"dev/changelog/#improved-documentation_14","title":"Improved Documentation","text":"<ul> <li>Document about how to activate and use a plugin. #227</li> </ul>"},{"location":"dev/changelog/#dependencies_20","title":"Dependencies","text":"<ul> <li>Test project on <code>pip 21.0</code>. #235</li> </ul>"},{"location":"dev/changelog/#release-v110-2021-01-18","title":"Release v1.1.0 (2021-01-18)","text":""},{"location":"dev/changelog/#features-improvements_74","title":"Features &amp; Improvements","text":"<ul> <li>Allow users to hide secrets from the <code>pyproject.toml</code>.</li> <li>Dynamically expand env variables in the URLs in dependencies and indexes.</li> <li>Ask whether to store the credentials provided by the user.</li> <li>A user-friendly error will show when credentials are not provided nor correct. #198</li> <li>Use a different package dir for 32-bit installation(Windows). #212</li> <li>Auto disable PEP 582 when a venv-like python is given as the interpreter path. #219</li> <li>Support specifying Python interpreter by <code>pdm use &lt;path-to-python-root&gt;</code>. #221</li> </ul>"},{"location":"dev/changelog/#bug-fixes_128","title":"Bug Fixes","text":"<ul> <li>Fix a bug of <code>PYTHONPATH</code> manipulation under Windows platform. #215</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_14","title":"Removals and Deprecations","text":"<ul> <li>Remove support of the old PEP 517 backend API path. #217</li> </ul>"},{"location":"dev/changelog/#release-v100-2021-01-05","title":"Release v1.0.0 (2021-01-05)","text":""},{"location":"dev/changelog/#bug-fixes_129","title":"Bug Fixes","text":"<ul> <li>Correctly build wheels for dependencies with build-requirements but without a specified build-backend #213</li> </ul>"},{"location":"dev/changelog/#release-v100b2-2020-12-29","title":"Release v1.0.0b2 (2020-12-29)","text":""},{"location":"dev/changelog/#features-improvements_75","title":"Features &amp; Improvements","text":"<ul> <li>Fallback to pypi.org when <code>/search</code> endpoint is not available on given index. #211</li> </ul>"},{"location":"dev/changelog/#bug-fixes_130","title":"Bug Fixes","text":"<ul> <li>Fix a bug that PDM fails to parse python version specifiers with more than 3 parts. #210</li> </ul>"},{"location":"dev/changelog/#release-v100b0-2020-12-24","title":"Release v1.0.0b0 (2020-12-24)","text":""},{"location":"dev/changelog/#features-improvements_76","title":"Features &amp; Improvements","text":"<ul> <li>Fully support of PEP 621 specification.</li> <li>Old format is deprecated at the same time.</li> <li>PDM will migrate the project file for you when old format is detected.</li> <li>Other metadata formats(<code>Poetry</code>, <code>Pipfile</code>, <code>flit</code>) can also be imported as PEP 621 metadata. #175</li> <li>Re-implement the <code>pdm search</code> to query the <code>/search</code> HTTP endpoint. #195</li> <li>Reuse the cached built wheels to accelerate the installation. #200</li> <li>Make update strategy and save strategy configurable in pdm config. #202</li> <li>Improve the error message to give more insight on what to do when resolution fails. #207</li> <li>Set <code>classifiers</code> dynamic in <code>pyproject.toml</code> template for autogeneration. #209</li> </ul>"},{"location":"dev/changelog/#bug-fixes_131","title":"Bug Fixes","text":"<ul> <li>Fix a bug that distributions are not removed clearly in parallel mode. #204</li> <li>Fix a bug that python specifier <code>is_subset()</code> returns incorrect result. #206</li> </ul>"},{"location":"dev/changelog/#release-v0123-2020-12-21","title":"Release v0.12.3 (2020-12-21)","text":""},{"location":"dev/changelog/#dependencies_21","title":"Dependencies","text":"<ul> <li>Pin <code>pdm-pep517</code> to <code>&lt;0.3.0</code>, this is the last version to support legacy project metadata format.</li> </ul>"},{"location":"dev/changelog/#release-v0122-2020-12-17","title":"Release v0.12.2 (2020-12-17)","text":""},{"location":"dev/changelog/#features-improvements_77","title":"Features &amp; Improvements","text":"<ul> <li>Update the lock file schema, move the file hashes to <code>[metadata.files]</code> table. #196</li> <li>Retry failed jobs when syncing packages. #197</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_15","title":"Removals and Deprecations","text":"<ul> <li>Drop <code>pip-shims</code> package as a dependency. #132</li> </ul>"},{"location":"dev/changelog/#miscellany_17","title":"Miscellany","text":"<ul> <li>Fix the cache path for CI. #199</li> </ul>"},{"location":"dev/changelog/#release-v0121-2020-12-14","title":"Release v0.12.1 (2020-12-14)","text":""},{"location":"dev/changelog/#features-improvements_78","title":"Features &amp; Improvements","text":"<ul> <li>Provide an option to export requirements from pyproject.toml #190</li> <li>For Windows users, <code>pdm --pep582</code> can enable PEP 582 globally by manipulating the WinReg. #191</li> </ul>"},{"location":"dev/changelog/#bug-fixes_132","title":"Bug Fixes","text":"<ul> <li>Inject <code>__pypackages__</code> into <code>PATH</code> env var during <code>pdm run</code>. #193</li> </ul>"},{"location":"dev/changelog/#release-v0120-2020-12-08","title":"Release v0.12.0 (2020-12-08)","text":""},{"location":"dev/changelog/#features-improvements_79","title":"Features &amp; Improvements","text":"<ul> <li>Improve the user experience of <code>pdm run</code>:</li> <li>Add a special key in tool.pdm.scripts that holds configurations shared by all scripts.</li> <li>Support loading env var from a dot-env file.</li> <li>Add a flag <code>-s/--site-packages</code> to include system site-packages when running. #178</li> <li>Now PEP 582 can be enabled in the Python interpreter directly! #181</li> </ul>"},{"location":"dev/changelog/#bug-fixes_133","title":"Bug Fixes","text":"<ul> <li>Ensure <code>setuptools</code> is installed before invoking editable install script. #174</li> <li>Require <code>wheel</code> not <code>wheels</code> for global projects #182</li> <li>Write a <code>sitecustomize.py</code> instead of a <code>.pth</code> file to enable PEP 582. Thanks @Aloxaf.   Update <code>get_package_finder()</code> to be compatible with <code>pip 20.3</code>. #185</li> <li>Fix the help messages of commands \"cache\" and \"remove\" #187</li> </ul>"},{"location":"dev/changelog/#release-v0110-2020-11-20","title":"Release v0.11.0 (2020-11-20)","text":""},{"location":"dev/changelog/#features-improvements_80","title":"Features &amp; Improvements","text":"<ul> <li>Support custom script shortcuts in <code>pyproject.toml</code>.</li> <li>Support custom script shortcuts defined in <code>[tool.pdm.scripts]</code> section.</li> <li>Add <code>pdm run --list/-l</code> to show the list of script shortcuts. #168</li> <li>Patch the halo library to support parallel spinners.</li> <li>Change the looking of <code>pdm install</code>. #169</li> </ul>"},{"location":"dev/changelog/#bug-fixes_134","title":"Bug Fixes","text":"<ul> <li>Fix a bug that package's marker fails to propagate to its grandchildren if they have already been resolved. #170</li> <li>Fix a bug that bare version specifiers in Poetry project can't be converted correctly. #172</li> <li>Fix the build error that destination directory is not created automatically. #173</li> </ul>"},{"location":"dev/changelog/#release-v0102-2020-11-05","title":"Release v0.10.2 (2020-11-05)","text":""},{"location":"dev/changelog/#bug-fixes_135","title":"Bug Fixes","text":"<ul> <li>Building editable distribution does not install <code>build-system.requires</code> anymore. #167</li> </ul>"},{"location":"dev/changelog/#release-v0101-2020-11-04","title":"Release v0.10.1 (2020-11-04)","text":""},{"location":"dev/changelog/#bug-fixes_136","title":"Bug Fixes","text":"<ul> <li>Switch the PEP 517 build frontend from <code>build</code> to a home-grown version. #162</li> <li>Synchronize the output of <code>LogWrapper</code>. #164</li> <li>Fix a bug that <code>is_subset</code> and <code>is_superset</code> may return wrong result when wildcard excludes overlaps with the upper bound. #165</li> </ul>"},{"location":"dev/changelog/#release-v0100-2020-10-20","title":"Release v0.10.0 (2020-10-20)","text":""},{"location":"dev/changelog/#features-improvements_81","title":"Features &amp; Improvements","text":"<ul> <li>Change to Git style config command. #157</li> <li>Add a command to generate scripts for autocompletion, which is backed by <code>pycomplete</code>. #159</li> </ul>"},{"location":"dev/changelog/#bug-fixes_137","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>sitecustomize.py</code> incorrectly gets injected into the editable console scripts. #158</li> </ul>"},{"location":"dev/changelog/#release-v092-2020-10-13","title":"Release v0.9.2 (2020-10-13)","text":""},{"location":"dev/changelog/#features-improvements_82","title":"Features &amp; Improvements","text":"<ul> <li>Cache the built wheels to accelerate resolution and installation process. #153</li> </ul>"},{"location":"dev/changelog/#bug-fixes_138","title":"Bug Fixes","text":"<ul> <li>Fix a bug that no wheel is matched when finding candidates to install. #155</li> <li>Fix a bug that installation in parallel will cause encoding initialization error on Ubuntu. #156</li> </ul>"},{"location":"dev/changelog/#release-v091-2020-10-13","title":"Release v0.9.1 (2020-10-13)","text":""},{"location":"dev/changelog/#features-improvements_83","title":"Features &amp; Improvements","text":"<ul> <li>Display plain text instead of spinner bar under verbose mode. #150</li> </ul>"},{"location":"dev/changelog/#bug-fixes_139","title":"Bug Fixes","text":"<ul> <li>Fix a bug that the result of <code>find_matched()</code> is exhausted when accessed twice. #149</li> </ul>"},{"location":"dev/changelog/#release-v090-2020-10-08","title":"Release v0.9.0 (2020-10-08)","text":""},{"location":"dev/changelog/#features-improvements_84","title":"Features &amp; Improvements","text":"<ul> <li>Allow users to combine several dependency sections to form an extra require. #131</li> <li>Split the PEP 517 backend to its own(battery included) package. #134</li> <li>Add a new option to list command to show reverse dependency graph. #137</li> </ul>"},{"location":"dev/changelog/#bug-fixes_140","title":"Bug Fixes","text":"<ul> <li>Fix a bug that spaces in path causes requirement parsing error. #138</li> <li>Fix a bug that requirement's python constraint is not respected when resolving. #141</li> </ul>"},{"location":"dev/changelog/#dependencies_22","title":"Dependencies","text":"<ul> <li>Update <code>pdm-pep517</code> to <code>0.2.0</code> that supports reading version from SCM. #146</li> </ul>"},{"location":"dev/changelog/#miscellany_18","title":"Miscellany","text":"<ul> <li>Add Python 3.9 to the CI version matrix to verify. #144</li> </ul>"},{"location":"dev/changelog/#release-v087-2020-09-04","title":"Release v0.8.7 (2020-09-04)","text":""},{"location":"dev/changelog/#bug-fixes_141","title":"Bug Fixes","text":"<ul> <li>Fix a compatibility issue with <code>wheel==0.35</code>. #135</li> </ul>"},{"location":"dev/changelog/#release-v086-2020-07-09","title":"Release v0.8.6 (2020-07-09)","text":""},{"location":"dev/changelog/#bug-fixes_142","title":"Bug Fixes","text":"<ul> <li>Fix a bug that extra sources are not respected when fetching distributions. #127</li> </ul>"},{"location":"dev/changelog/#release-v085-2020-06-24","title":"Release v0.8.5 (2020-06-24)","text":""},{"location":"dev/changelog/#bug-fixes_143","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>pdm export</code> fails when the project doesn't have <code>name</code> property. #126</li> </ul>"},{"location":"dev/changelog/#dependencies_23","title":"Dependencies","text":"<ul> <li>Upgrade dependency <code>pip</code> to <code>20.1</code>. #125</li> </ul>"},{"location":"dev/changelog/#release-v084-2020-05-21","title":"Release v0.8.4 (2020-05-21)","text":""},{"location":"dev/changelog/#features-improvements_85","title":"Features &amp; Improvements","text":"<ul> <li>Add a new command <code>export</code> to export to alternative formats. #117</li> </ul>"},{"location":"dev/changelog/#miscellany_19","title":"Miscellany","text":"<ul> <li>Add Dockerfile and pushed to Docker Hub. #122</li> </ul>"},{"location":"dev/changelog/#release-v083-2020-05-15","title":"Release v0.8.3 (2020-05-15)","text":""},{"location":"dev/changelog/#bug-fixes_144","title":"Bug Fixes","text":"<ul> <li>Fix the version constraint parsing of wheel metadata. #120</li> </ul>"},{"location":"dev/changelog/#release-v082-2020-05-03","title":"Release v0.8.2 (2020-05-03)","text":""},{"location":"dev/changelog/#bug-fixes_145","title":"Bug Fixes","text":"<ul> <li>Update resolvers to <code>resolvelib</code> 0.4.0. #118</li> </ul>"},{"location":"dev/changelog/#release-v081-2020-04-22","title":"Release v0.8.1 (2020-04-22)","text":""},{"location":"dev/changelog/#dependencies_24","title":"Dependencies","text":"<ul> <li>Switch to upstream <code>resolvelib 0.3.0</code>. #116</li> </ul>"},{"location":"dev/changelog/#release-v080-2020-04-20","title":"Release v0.8.0 (2020-04-20)","text":""},{"location":"dev/changelog/#features-improvements_86","title":"Features &amp; Improvements","text":"<ul> <li>Add a new command to search for packages #111</li> <li>Add <code>show</code> command to show package metadata. #114</li> </ul>"},{"location":"dev/changelog/#bug-fixes_146","title":"Bug Fixes","text":"<ul> <li>Fix a bug that environment markers cannot be evaluated correctly if extras are connected with \"or\". #107</li> <li>Don't consult PyPI JSON API by default for package metadata. #112</li> <li>Eliminate backslashes in markers for TOML documents. #115</li> </ul>"},{"location":"dev/changelog/#release-v071-2020-04-13","title":"Release v0.7.1 (2020-04-13)","text":""},{"location":"dev/changelog/#bug-fixes_147","title":"Bug Fixes","text":"<ul> <li>Editable packages requires <code>setuptools</code> to be installed in the isolated environment.</li> </ul>"},{"location":"dev/changelog/#release-v070-2020-04-12","title":"Release v0.7.0 (2020-04-12)","text":""},{"location":"dev/changelog/#features-improvements_87","title":"Features &amp; Improvements","text":"<ul> <li>Disable loading of site-packages under PEP 582 mode. #100</li> </ul>"},{"location":"dev/changelog/#bug-fixes_148","title":"Bug Fixes","text":"<ul> <li>Fix a bug that TOML parsing error is not correctly captured. #101</li> <li>Fix a bug of building wheels with C extensions that the platform in file name is incorrect. #99</li> </ul>"},{"location":"dev/changelog/#release-v065-2020-04-07","title":"Release v0.6.5 (2020-04-07)","text":""},{"location":"dev/changelog/#bug-fixes_149","title":"Bug Fixes","text":"<ul> <li>Unix style executable script suffix is missing.</li> </ul>"},{"location":"dev/changelog/#release-v064-2020-04-07","title":"Release v0.6.4 (2020-04-07)","text":""},{"location":"dev/changelog/#features-improvements_88","title":"Features &amp; Improvements","text":"<ul> <li>Update shebang lines in the executable scripts when doing <code>pdm use</code>. #96</li> <li>Auto-detect commonly used venv directories. #97</li> </ul>"},{"location":"dev/changelog/#release-v063-2020-03-30","title":"Release v0.6.3 (2020-03-30)","text":""},{"location":"dev/changelog/#bug-fixes_150","title":"Bug Fixes","text":"<ul> <li>Fix a bug of moving files across different file system. #95</li> </ul>"},{"location":"dev/changelog/#release-v062-2020-03-29","title":"Release v0.6.2 (2020-03-29)","text":""},{"location":"dev/changelog/#bug-fixes_151","title":"Bug Fixes","text":"<ul> <li>Validate user input for <code>python_requires</code> when initializing project. #89</li> <li>Ensure <code>wheel</code> package is available before building packages. #90</li> <li>Fix an issue of remove command that will unexpectedly uninstall packages in default section. #92</li> </ul>"},{"location":"dev/changelog/#dependencies_25","title":"Dependencies","text":"<ul> <li>Update dependencies <code>pythonfinder</code>, <code>python-cfonts</code>, <code>pip-shims</code> and many others.   Drop dependency <code>vistir</code>. #89</li> </ul>"},{"location":"dev/changelog/#release-v061-2020-03-25","title":"Release v0.6.1 (2020-03-25)","text":""},{"location":"dev/changelog/#features-improvements_89","title":"Features &amp; Improvements","text":"<ul> <li>Redirect output messages to log file for installation and locking. #84</li> </ul>"},{"location":"dev/changelog/#bug-fixes_152","title":"Bug Fixes","text":"<ul> <li>Fix a bug that parallel installation fails due to setuptools reinstalling. #83</li> </ul>"},{"location":"dev/changelog/#release-v060-2020-03-20","title":"Release v0.6.0 (2020-03-20)","text":""},{"location":"dev/changelog/#features-improvements_90","title":"Features &amp; Improvements","text":"<ul> <li>Support specifying build script for C extensions. #23</li> <li>Add test cases for <code>pdm build</code>. #81</li> <li>Make it configurable whether to consult PyPI JSON API since it may be not trustable.</li> <li>Support parallel installation.</li> <li>Add new command <code>pmd import</code> to import project metadata from <code>Pipfile</code>, <code>poetry</code>, <code>flit</code>, <code>requirements.txt</code>.   #79</li> <li><code>pdm init</code> and <code>pdm install</code> will auto-detect possible files that can be imported.</li> </ul>"},{"location":"dev/changelog/#bug-fixes_153","title":"Bug Fixes","text":"<ul> <li>Fix wheel builds when <code>package_dir</code> is mapped. #81</li> <li><code>pdm init</code> will use the current directory rather than finding the parents when global project is not activated.</li> </ul>"},{"location":"dev/changelog/#release-v050-2020-03-14","title":"Release v0.5.0 (2020-03-14)","text":""},{"location":"dev/changelog/#features-improvements_91","title":"Features &amp; Improvements","text":"<ul> <li>Introduce a super easy-to-extend plug-in system to PDM. #75</li> </ul>"},{"location":"dev/changelog/#improved-documentation_15","title":"Improved Documentation","text":"<ul> <li>Documentation on how to write a plugin. #75</li> </ul>"},{"location":"dev/changelog/#bug-fixes_154","title":"Bug Fixes","text":"<ul> <li>Fix a typo in metadata parsing from <code>plugins</code> to <code>entry_points</code></li> </ul>"},{"location":"dev/changelog/#release-v042-2020-03-13","title":"Release v0.4.2 (2020-03-13)","text":""},{"location":"dev/changelog/#features-improvements_92","title":"Features &amp; Improvements","text":"<ul> <li>Refactor the CLI part, switch from <code>click</code> to <code>argparse</code>, for better extensibility. #73</li> <li>Allow users to configure to install packages into venv when it is activated. #74</li> </ul>"},{"location":"dev/changelog/#release-v041-2020-03-11","title":"Release v0.4.1 (2020-03-11)","text":""},{"location":"dev/changelog/#features-improvements_93","title":"Features &amp; Improvements","text":"<ul> <li>Add a minimal dependency set for global project. #72</li> </ul>"},{"location":"dev/changelog/#release-v040-2020-03-10","title":"Release v0.4.0 (2020-03-10)","text":""},{"location":"dev/changelog/#features-improvements_94","title":"Features &amp; Improvements","text":"<ul> <li>Global project support</li> <li>Add a new option <code>-g/--global</code> to manage global project. The default location is at <code>~/.pdm/global-project</code>.</li> <li>Use the virtualenv interpreter when detected inside an activated venv.</li> <li>Add a new option <code>-p/--project</code> to select project root other than the default one. #30</li> <li>Add a new command <code>pdm config del</code> to delete an existing config item. #71</li> </ul>"},{"location":"dev/changelog/#bug-fixes_155","title":"Bug Fixes","text":"<ul> <li>Fix a URL parsing issue that username will be dropped in the SSH URL. #68</li> </ul>"},{"location":"dev/changelog/#improved-documentation_16","title":"Improved Documentation","text":"<ul> <li>Add docs for global project and selecting project path. #30</li> </ul>"},{"location":"dev/changelog/#release-v032-2020-03-08","title":"Release v0.3.2 (2020-03-08)","text":""},{"location":"dev/changelog/#features-improvements_95","title":"Features &amp; Improvements","text":"<ul> <li>Display all available Python interpreters if users don't give one in <code>pdm init</code>. #67</li> </ul>"},{"location":"dev/changelog/#bug-fixes_156","title":"Bug Fixes","text":"<ul> <li>Regard <code>4.0</code> as infinite upper bound when checking subsetting. #66</li> </ul>"},{"location":"dev/changelog/#release-v031-2020-03-07","title":"Release v0.3.1 (2020-03-07)","text":""},{"location":"dev/changelog/#bug-fixes_157","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>ImpossiblePySpec</code>'s hash clashes with normal one.</li> </ul>"},{"location":"dev/changelog/#release-v030-2020-02-28","title":"Release v0.3.0 (2020-02-28)","text":""},{"location":"dev/changelog/#features-improvements_96","title":"Features &amp; Improvements","text":"<ul> <li>Add a new command <code>pdm config</code> to inspect configurations. #26</li> <li>Add a new command <code>pdm cache clear</code> to clean caches. #63</li> </ul>"},{"location":"dev/changelog/#bug-fixes_158","title":"Bug Fixes","text":"<ul> <li>Correctly show dependency graph when circular dependencies exist. #62</li> </ul>"},{"location":"dev/changelog/#improved-documentation_17","title":"Improved Documentation","text":"<ul> <li>Write the initial documentation for PDM. #14</li> </ul>"},{"location":"dev/changelog/#release-v026-2020-02-25","title":"Release v0.2.6 (2020-02-25)","text":""},{"location":"dev/changelog/#features-improvements_97","title":"Features &amp; Improvements","text":"<ul> <li>Improve the user interface of selecting Python interpreter. #54</li> </ul>"},{"location":"dev/changelog/#bug-fixes_159","title":"Bug Fixes","text":"<ul> <li>Fix the wheel installer to correctly unparse the flags of console scripts. #56</li> <li>Fix a bug that OS-dependent hashes are not saved. #57</li> </ul>"},{"location":"dev/changelog/#release-v025-2020-02-22","title":"Release v0.2.5 (2020-02-22)","text":""},{"location":"dev/changelog/#features-improvements_98","title":"Features &amp; Improvements","text":"<ul> <li>Allow specifying Python interpreter via <code>--python</code> option in <code>pdm init</code>. #49</li> <li>Set <code>python_requires</code> when initializing and defaults to <code>&gt;={current_version}</code>. #50</li> </ul>"},{"location":"dev/changelog/#bug-fixes_160","title":"Bug Fixes","text":"<ul> <li>Always consider wheels before tarballs; correctly merge markers from different parents. #47</li> <li>Filter out incompatible wheels when installing. #48</li> </ul>"},{"location":"dev/changelog/#release-v024-2020-02-21","title":"Release v0.2.4 (2020-02-21)","text":""},{"location":"dev/changelog/#bug-fixes_161","title":"Bug Fixes","text":"<ul> <li>Use the project local interpreter to build wheels. #43</li> <li>Correctly merge Python specifiers when possible. #4</li> </ul>"},{"location":"dev/changelog/#release-v023-2020-02-21","title":"Release v0.2.3 (2020-02-21)","text":""},{"location":"dev/changelog/#bug-fixes_162","title":"Bug Fixes","text":"<ul> <li>Fix a bug that editable build generates a malformed <code>setup.py</code>.</li> </ul>"},{"location":"dev/changelog/#release-v022-2020-02-20","title":"Release v0.2.2 (2020-02-20)","text":""},{"location":"dev/changelog/#features-improvements_99","title":"Features &amp; Improvements","text":"<ul> <li>Add a fancy greeting banner when user types <code>pdm --help</code>. #42</li> </ul>"},{"location":"dev/changelog/#bug-fixes_163","title":"Bug Fixes","text":"<ul> <li>Fix the RECORD file in built wheel. #41</li> </ul>"},{"location":"dev/changelog/#dependencies_26","title":"Dependencies","text":"<ul> <li>Add dependency <code>python-cfonts</code> to display banner. #42</li> </ul>"},{"location":"dev/changelog/#release-v021-2020-02-18","title":"Release v0.2.1 (2020-02-18)","text":""},{"location":"dev/changelog/#bug-fixes_164","title":"Bug Fixes","text":"<ul> <li>Fix a bug that short python_version markers can't be parsed correctly. #38</li> <li>Make <code>_editable_intall.py</code> compatible with Py2.</li> </ul>"},{"location":"dev/changelog/#release-v020-2020-02-14","title":"Release v0.2.0 (2020-02-14)","text":""},{"location":"dev/changelog/#features-improvements_100","title":"Features &amp; Improvements","text":"<ul> <li>New option: <code>pdm list --graph</code> to show a dependency graph of the working set. #10</li> <li>New option: <code>pdm update --unconstrained</code> to ignore the version constraint of given packages. #13</li> <li>Improve the error message when project is not initialized before running commands. #19</li> <li>Pinned candidates in lock file are reused when relocking during <code>pdm install</code>. #33</li> <li>Use the pyenv interpreter value if pyenv is installed. #36</li> <li>Introduce a new command <code>pdm info</code> to show project environment information. #9</li> </ul>"},{"location":"dev/changelog/#bug-fixes_165","title":"Bug Fixes","text":"<ul> <li>Fix a bug that candidate hashes will be lost when reused. #11</li> </ul>"},{"location":"dev/changelog/#dependencies_27","title":"Dependencies","text":"<ul> <li>Update <code>pip</code> to <code>20.0</code>, update <code>pip_shims</code> to <code>0.5.0</code>. #28</li> </ul>"},{"location":"dev/changelog/#miscellany_20","title":"Miscellany","text":"<ul> <li>Add a script named <code>setup_dev.py</code> for the convenience to setup pdm for development. #29</li> </ul>"},{"location":"dev/changelog/#release-v012-2020-02-09","title":"Release v0.1.2 (2020-02-09)","text":""},{"location":"dev/changelog/#features","title":"Features","text":"<ul> <li>New command pdm use to switch python versions. #8</li> <li>New option pdm list --graph to show a dependency graph. #10</li> <li>Read metadata from lockfile when pinned candidate is reused.</li> </ul>"},{"location":"dev/changelog/#release-v011-2020-02-07","title":"Release v0.1.1 (2020-02-07)","text":""},{"location":"dev/changelog/#features_1","title":"Features","text":"<ul> <li>Get version from the specified file. #6</li> <li>Add column header to pdm list output.</li> </ul>"},{"location":"dev/changelog/#release-v010-2020-02-07","title":"Release v0.1.0 (2020-02-07)","text":""},{"location":"dev/changelog/#bugfixes","title":"Bugfixes","text":"<ul> <li>Pass exit code to parent process in pdm run.</li> <li>Fix error handling for CLI. #19</li> </ul>"},{"location":"dev/changelog/#miscellany_21","title":"Miscellany","text":"<ul> <li>Refactor the installer mocking for tests.</li> </ul>"},{"location":"dev/changelog/#release-v005-2020-01-22","title":"Release v0.0.5 (2020-01-22)","text":""},{"location":"dev/changelog/#improvements","title":"Improvements","text":"<ul> <li>Ensure pypi index url is fetched in addition to the source settings. #3</li> </ul>"},{"location":"dev/changelog/#bugfixes_1","title":"Bugfixes","text":"<ul> <li>Fix an issue that leading \"c\"s are mistakenly stripped. #5</li> <li>Fix an error with PEP 517 building.</li> </ul>"},{"location":"dev/changelog/#release-v004-2020-01-22","title":"Release v0.0.4 (2020-01-22)","text":""},{"location":"dev/changelog/#improvements_1","title":"Improvements","text":"<ul> <li>Fix editable installation, now editable scripts can also be executed from outside!</li> <li>Content hash is calculated based on dependencies and sources, not other metadata.</li> </ul>"},{"location":"dev/changelog/#bugfixes_2","title":"Bugfixes","text":"<ul> <li>Fix an issue that editable distributions can not be removed.</li> </ul>"},{"location":"dev/changelog/#release-v003-2020-01-22","title":"Release v0.0.3 (2020-01-22)","text":""},{"location":"dev/changelog/#features_2","title":"Features","text":"<ul> <li>Add <code>pdm init</code> to bootstrap a project.</li> </ul>"},{"location":"dev/changelog/#release-v002-2020-01-22","title":"Release v0.0.2 (2020-01-22)","text":""},{"location":"dev/changelog/#features_3","title":"Features","text":"<ul> <li>A complete functioning PEP 517 build backend.</li> <li><code>pdm build</code> command.</li> </ul>"},{"location":"dev/changelog/#miscellany_22","title":"Miscellany","text":"<ul> <li>Add a Chinese README</li> </ul>"},{"location":"dev/changelog/#features_4","title":"Features","text":"<ul> <li>Add <code>pdm init</code> to bootstrap a project.</li> </ul>"},{"location":"dev/changelog/#release-v001-2020-01-20","title":"Release v0.0.1 (2020-01-20)","text":""},{"location":"dev/changelog/#features_5","title":"Features","text":"<ul> <li>A dependency resolver that just works.</li> <li>A PEP 582 installer.</li> <li>PEP 440 version specifiers.</li> <li>PEP 508 environment markers.</li> <li>Running scripts with PEP 582 local packages.</li> <li>Console scripts are injected with local paths.</li> <li>A neat CLI.</li> <li>add, lock, list, update, remove commands.</li> <li>PEP 517 build backends.</li> <li>Continuous Integration.</li> </ul>"},{"location":"dev/contributing/","title":"Contributing to PDM","text":"<p>First off, thanks for taking the time to contribute! Contributions include but are not restricted to:</p> <ul> <li>Reporting bugs</li> <li>Contributing to code</li> <li>Writing tests</li> <li>Writing documentation</li> </ul> <p>The following is a set of guidelines for contributing.</p>"},{"location":"dev/contributing/#a-recommended-flow-of-contributing-to-an-open-source-project","title":"A recommended flow of contributing to an Open Source project","text":"<p>This section is for beginners to OSS. If you are an experienced OSS developer, you can skip this section.</p> <ol> <li>First, fork this project to your own namespace using the fork button at the top right of the repository page.</li> <li>Clone the upstream repository to local:    <pre><code>git clone https://github.com/pdm-project/pdm.git\n# Or if you prefer SSH clone:\ngit clone git@github.com:pdm-project/pdm.git\n</code></pre></li> <li>Add the fork as a new remote:    <pre><code>git remote add fork https://github.com/yourname/pdm.git\ngit fetch fork\n</code></pre>    where <code>fork</code> is the remote name of the fork repository.</li> </ol> <p>ProTips:</p> <ol> <li>Don't modify code on the main branch, the main branch should always keep track of origin/main.</li> </ol> <p>To update main branch to date:</p> <pre><code>git pull origin main\n# In rare cases that your local main branch diverges from the remote main:\ngit fetch origin &amp;&amp; git reset --hard main\n</code></pre> <ol> <li>Create a new branch based on the up-to-date main branch for new patches.</li> <li>Create a Pull Request from that patch branch.</li> </ol>"},{"location":"dev/contributing/#local-development","title":"Local development","text":"<p>We recommend working in a virtual environment. Feel free to create a virtual environment with either the <code>venv</code> module or the <code>virtualenv</code> tool. For example:</p> <pre><code>python -m venv .venv\n. .venv/bin/activate  # linux\n.venv/Scripts/activate  # windows\n</code></pre> <p>Make sure your <code>pip</code> is newer than <code>21.3</code> to install PDM in develop/editable mode.</p> <pre><code>python -m pip install -U \"pip&gt;=21.3\"\npython -m pip install -e .\n</code></pre> <p>Make sure PDM uses the virtual environment you just created:</p> <pre><code>pdm config -l python.use_venv true\npdm config -l venv.in_project true\n</code></pre> <p>Install PDM development dependencies:</p> <pre><code>pdm install\n</code></pre> <p>Now, all dependencies are installed into the Python environment you chose, which will be used for development after this point.</p>"},{"location":"dev/contributing/#run-tests","title":"Run tests","text":"<pre><code>pdm run test\n</code></pre> <p>The test suite is still simple and needs expansion! Please help write more test cases.</p> <p>Note</p> <p>You can also run your test suite against all supported Python version using <code>tox</code> with the <code>tox-pdm</code> plugin. You can either run it by yourself with:</p> <pre><code>tox\n</code></pre> <p>or from <code>pdm</code> with:</p> <pre><code>pdm run tox\n</code></pre>"},{"location":"dev/contributing/#code-style","title":"Code style","text":"<p>PDM uses <code>pre-commit</code> for linting. Install <code>pre-commit</code> first, for example with pip or pipx:</p> <pre><code>python -m pip install pre-commit\n</code></pre> <pre><code>pipx install pre-commit\n</code></pre> <p>Then initialize <code>pre-commit</code>:</p> <pre><code>pre-commit install\n</code></pre> <p>You can now lint the code with:</p> <pre><code>pdm run lint\n</code></pre> <p>PDM uses <code>black</code> for code style and <code>isort</code> for sorting import statements. If you are not following them, the CI will fail and your Pull Request will not be merged.</p>"},{"location":"dev/contributing/#news-fragments","title":"News fragments","text":"<p>When you make changes such as fixing a bug or adding a feature, you must add a news fragment describing your change. News fragments are placed in the <code>news/</code> directory, and should be named according to this pattern: <code>&lt;issue_num&gt;.&lt;issue_type&gt;.md</code> (e.g., <code>566.bugfix.md</code>).</p>"},{"location":"dev/contributing/#issue-types","title":"Issue Types","text":"<ul> <li><code>feature</code>: Features and improvements</li> <li><code>bugfix</code>: Bug fixes</li> <li><code>refactor</code>: Code restructures</li> <li><code>doc</code>: Added or improved documentation</li> <li><code>dep</code>: Changes to dependencies</li> <li><code>removal</code>: Removals or deprecations in the API</li> <li><code>misc</code>: Miscellaneous changes that don't fit any of the other categories</li> </ul> <p>The contents of the file should be a single sentence in the imperative mood that describes your changes. (e.g., <code>Deduplicate the plugins list.</code> ) See entries in the Change Log for more examples.</p>"},{"location":"dev/contributing/#preview-the-documentation","title":"Preview the documentation","text":"<p>If you make some changes to the <code>docs/</code> and you want to preview the build result, simply do:</p> <pre><code>pdm run doc\n</code></pre>"},{"location":"dev/contributing/#release","title":"Release","text":"<p>Once all changes are done and ready to release, you can preview the changelog contents by running:</p> <pre><code>pdm run release --dry-run\n</code></pre> <p>Make sure the next version and the changelog are as expected in the output.</p> <p>Then cut a release on the main branch:</p> <pre><code>pdm run release\n</code></pre> <p>GitHub action will create the release and upload the distributions to PyPI.</p> <p>Read more options about version bumping by <code>pdm run release --help</code>.</p>"},{"location":"dev/fixtures/","title":"Pytest fixtures","text":"<p>Some reusable fixtures for <code>pytest</code>.</p> <p>+++ 2.4.0</p> <p>To enable them in your test, add <code>pdm.pytest</code> as a plugin. You can do so in your root <code>conftest.py</code>:</p> conftest.py<pre><code># single plugin\npytest_plugins = \"pytest.plugin\"\n\n# many plugins\npytest_plugins = [\n    ...\n    \"pdm.pytest\",\n    ...\n]\n</code></pre>"},{"location":"dev/fixtures/#pdm.pytest.IndexMap","title":"<code>IndexMap = Dict[str, Path]</code>  <code>module-attribute</code>","text":"<p>Path some root-relative http paths to some local paths</p>"},{"location":"dev/fixtures/#pdm.pytest.IndexOverrides","title":"<code>IndexOverrides = Dict[str, str]</code>  <code>module-attribute</code>","text":"<p>PyPI indexes overrides fixture format</p>"},{"location":"dev/fixtures/#pdm.pytest.IndexesDefinition","title":"<code>IndexesDefinition = Dict[str, Union[Tuple[IndexMap, IndexOverrides, bool], IndexMap]]</code>  <code>module-attribute</code>","text":"<p>Mock PyPI indexes format</p>"},{"location":"dev/fixtures/#pdm.pytest.Distribution","title":"<code>Distribution</code>","text":"<p>A mock Distribution</p>"},{"location":"dev/fixtures/#pdm.pytest.LocalFileAdapter","title":"<code>LocalFileAdapter</code>","text":"<p>         Bases: <code>requests.adapters.BaseAdapter</code></p> <p>A local file adapter for request.</p> <p>Allows to mock some HTTP requests with some local files</p>"},{"location":"dev/fixtures/#pdm.pytest.MockWorkingSet","title":"<code>MockWorkingSet</code>","text":"<p>         Bases: <code>collections.abc.MutableMapping</code></p> <p>A mock working set</p>"},{"location":"dev/fixtures/#pdm.pytest.PDMCallable","title":"<code>PDMCallable</code>","text":"<p>         Bases: <code>Protocol</code></p> <p>The PDM fixture callable signature</p>"},{"location":"dev/fixtures/#pdm.pytest.PDMCallable.__call__","title":"<code>__call__(args, strict=False, input=None, obj=None, env=None, **kwargs)</code>","text":"<p>Parameters:</p> Name Type Description Default <code>args</code> <code>str | list[str]</code> <p>the command arguments as a single lexable string or a strings array</p> required <code>strict</code> <code>bool</code> <p>raise an exception on failure instead of returning if enabled</p> <code>False</code> <code>input</code> <code>str | None</code> <p>an optional string to be submitted too <code>stdin</code></p> <code>None</code> <code>obj</code> <code>Project | None</code> <p>an optional existing <code>Project</code>.</p> <code>None</code> <code>env</code> <code>Mapping[str, str] | None</code> <p>override the environment variables with those</p> <code>None</code> <p>Returns:</p> Type Description <code>RunResult</code> <p>The command result</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult","title":"<code>RunResult</code>  <code>dataclass</code>","text":"<p>Store a command execution result.</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.exception","title":"<code>exception: Exception | None = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":"<p>If set, the exception raised on execution</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.exit_code","title":"<code>exit_code: int</code>  <code>instance-attribute</code>","text":"<p>The execution exit code</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.output","title":"<code>output: str</code>  <code>property</code>","text":"<p>The execution <code>stdout</code> output (<code>stdout</code> alias)</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.outputs","title":"<code>outputs: str</code>  <code>property</code>","text":"<p>The execution <code>stdout</code> and <code>stderr</code> outputs concatenated</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.stderr","title":"<code>stderr: str</code>  <code>instance-attribute</code>","text":"<p>The execution <code>stderr</code> output</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.stdout","title":"<code>stdout: str</code>  <code>instance-attribute</code>","text":"<p>The execution <code>stdout</code> output</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.print","title":"<code>print()</code>","text":"<p>A debugging facility</p>"},{"location":"dev/fixtures/#pdm.pytest.TestRepository","title":"<code>TestRepository</code>","text":"<p>         Bases: <code>BaseRepository</code></p> <p>A mock repository to ease testing dependencies</p>"},{"location":"dev/fixtures/#pdm.pytest.build_env","title":"<code>build_env(build_env_wheels, tmp_path_factory)</code>","text":"<p>A fixture build environment</p> <p>Parameters:</p> Name Type Description Default <code>build_env_wheels</code> <code>Iterable[Path]</code> <p>a list of wheel to install in the environment</p> required <p>Returns:</p> Type Description <code>Path</code> <p>The build environment temporary path</p>"},{"location":"dev/fixtures/#pdm.pytest.build_env_wheels","title":"<code>build_env_wheels()</code>","text":"<p>Expose some wheels to be installed in the build environment.</p> <p>Override to provide your owns.</p> <p>Returns:</p> Type Description <code>Iterable[Path]</code> <p>a list of wheels paths to install</p>"},{"location":"dev/fixtures/#pdm.pytest.local_finder_artifacts","title":"<code>local_finder_artifacts()</code>","text":"<p>The local finder search path as a fixture</p> <p>Override to provides your own artifacts.</p> <p>Returns:</p> Type Description <code>Path</code> <p>The path to the artifacts root</p>"},{"location":"dev/fixtures/#pdm.pytest.pdm","title":"<code>pdm(core, monkeypatch)</code>","text":"<p>A fixture allowing to execute PDM commands</p> <p>Returns:</p> Type Description <code>PDMCallable</code> <p>A <code>pdm</code> fixture command.</p>"},{"location":"dev/fixtures/#pdm.pytest.project","title":"<code>project(project_no_init)</code>","text":"<p>A fixture creating an initialized test project for the current test.</p> <p>Returns:</p> Type Description <code>Project</code> <p>The initialized project</p>"},{"location":"dev/fixtures/#pdm.pytest.project_no_init","title":"<code>project_no_init(tmp_path, mocker, core, pdm_session, monkeypatch, build_env)</code>","text":"<p>A fixture creating a non-initialized test project for the current test.</p> <p>Returns:</p> Type Description <code>Project</code> <p>The non-initialized project</p>"},{"location":"dev/fixtures/#pdm.pytest.pypi_indexes","title":"<code>pypi_indexes()</code>","text":"<p>Provides some mocked PyPI entries</p> <p>Returns:</p> Type Description <code>IndexesDefinition</code> <p>a definition of the mocked indexes</p>"},{"location":"dev/fixtures/#pdm.pytest.remove_pep582_path_from_pythonpath","title":"<code>remove_pep582_path_from_pythonpath(pythonpath)</code>","text":"<p>Remove all pep582 paths of PDM from PYTHONPATH</p>"},{"location":"dev/fixtures/#pdm.pytest.repository","title":"<code>repository(project, mocker, repository_pypi_json, local_finder)</code>","text":"<p>A fixture providing a mock PyPI repository</p> <p>Returns:</p> Type Description <code>TestRepository</code> <p>A mock repository</p>"},{"location":"dev/fixtures/#pdm.pytest.repository_pypi_json","title":"<code>repository_pypi_json()</code>","text":"<p>The test repository fake PyPI definition path as a fixture</p> <p>Override to provides your own definition path.</p> <p>Returns:</p> Type Description <code>Path</code> <p>The path to a fake PyPI repository JSON definition</p>"},{"location":"dev/fixtures/#pdm.pytest.venv_backends","title":"<code>venv_backends(project, request)</code>","text":"<p>A fixture iterating over <code>venv</code> backends</p>"},{"location":"dev/fixtures/#pdm.pytest.working_set","title":"<code>working_set(mocker, repository)</code>","text":"<p>a mock working set as a fixture</p> <p>Returns:</p> Type Description <code>MockWorkingSet</code> <p>a mock working set</p>"},{"location":"dev/write/","title":"PDM Plugins","text":"<p>PDM is aiming at being a community driven package manager. It is shipped with a full-featured plug-in system, with which you can:</p> <ul> <li>Develop a new command for PDM</li> <li>Add additional options to existing PDM commands</li> <li>Change PDM's behavior by reading additional config items</li> <li>Control the process of dependency resolution or installation</li> </ul>"},{"location":"dev/write/#what-should-a-plugin-do","title":"What should a plugin do","text":"<p>The core PDM project focuses on dependency management and package publishing. Other functionalities you wish to integrate with PDM are preferred to lie in their own plugins and released as standalone PyPI projects. In case the plugin is considered a good supplement of the core project it may have a chance to be absorbed into PDM.</p>"},{"location":"dev/write/#write-your-own-plugin","title":"Write your own plugin","text":"<p>In the following sections, I will show an example of adding a new command <code>hello</code> which reads the <code>hello.name</code> config.</p>"},{"location":"dev/write/#write-the-command","title":"Write the command","text":"<p>The PDM's CLI module is designed in a way that user can easily \"inherit and modify\". To write a new command:</p> <pre><code>from pdm.cli.commands.base import BaseCommand\n\nclass HelloCommand(BaseCommand):\n\"\"\"Say hello to the specified person.\n    If none is given, will read from \"hello.name\" config.\n    \"\"\"\n\n    def add_arguments(self, parser):\n        parser.add_argument(\"-n\", \"--name\", help=\"the person's name to whom you greet\")\n\n    def handle(self, project, options):\n        if not options.name:\n            name = project.config[\"hello.name\"]\n        else:\n            name = options.name\n        print(f\"Hello, {name}\")\n</code></pre> <p>First, let's create a new <code>HelloCommand</code> class inheriting from <code>pdm.cli.commands.base.BaseCommand</code>. It has two major functions:</p> <ul> <li><code>add_arguments()</code> to manipulate the argument parser passed as the only argument,   where you can add additional command line arguments to it</li> <li><code>handle()</code> to do something when the subcommand is matched, you can do nothing by writing a single <code>pass</code> statement.   It accepts two arguments: an <code>pdm.project.Project</code> object as the first one and the parsed <code>argparse.Namespace</code> object as the second.</li> </ul> <p>The document string will serve as the command help text, which will be shown in <code>pdm --help</code>.</p> <p>Besides, PDM's subcommand has two default options: <code>-v/--verbose</code> to change the verbosity level and <code>-g/--global</code> to enable global project. If you don't want these default options, override the <code>arguments</code> class attribute to a list of <code>pdm.cli.options.Option</code> objects, or assign it to an empty list to have no default options:</p> <pre><code>class HelloCommand(BaseCommand):\n\narguments = []\n</code></pre> <p>Note</p> <p>The default options are loaded first, then <code>add_arguments()</code> is called.</p>"},{"location":"dev/write/#register-the-command-to-the-core-object","title":"Register the command to the core object","text":"<p>Write a function somewhere in your plugin project. There is no limit on what the name of the function is, but the function should take only one argument -- the PDM core object:</p> <pre><code>def hello_plugin(core):\ncore.register_command(HelloCommand, \"hello\")\n</code></pre> <p>Call <code>core.register_command()</code> to register the command. The second argument as the name of the subcommand is optional. PDM will look for the <code>HelloCommand</code>'s <code>name</code> attribute if the name is not passed.</p>"},{"location":"dev/write/#add-a-new-config-item","title":"Add a new config item","text":"<p>Let's recall the first code snippet, <code>hello.name</code> config key is consulted for the name if not passed via the command line.</p> <pre><code>class HelloCommand(BaseCommand):\n\"\"\"Say hello to the specified person.\n    If none is given, will read from \"hello.name\" config.\n    \"\"\"\n\n    def add_arguments(self, parser):\n        parser.add_argument(\"-n\", \"--name\", help=\"the person's name to whom you greet\")\n\n    def handle(self, project, options):\n        if not options.name:\nname = project.config[\"hello.name\"]\nelse:\n            name = options.name\n        print(f\"Hello, {name}\")\n</code></pre> <p>Till now, if you query the config value by <code>pdm config get hello.name</code>, an error will pop up saying it is not a valid config key. You need to register the config item, too:</p> <pre><code>from pdm.project.config import ConfigItem\n\ndef hello_plugin(core):\n    core.register_command(HelloCommand, \"hello\")\ncore.add_config(\"hello.name\", ConfigItem(\"The person's name\", \"John\"))\n</code></pre> <p>where <code>ConfigItem</code> class takes 4 parameters, in the following order:</p> <ul> <li><code>description</code>: a description of the config item</li> <li><code>default</code>: default value of the config item</li> <li><code>global_only</code>: whether the config is allowed to set in home config only</li> <li><code>env_var</code>: the name of environment variable which will be read as the config value</li> </ul>"},{"location":"dev/write/#other-plugin-points","title":"Other plugin points","text":"<p>Besides of commands and configurations, the <code>core</code> object exposes some other methods and attributes to override. PDM also provides some signals you can listen to. Please read the API reference for more details.</p>"},{"location":"dev/write/#tips-about-developing-a-pdm-plugin","title":"Tips about developing a PDM plugin","text":"<p>When developing a plugin, one hopes to activate and plugin in development and get updated when the code changes.</p> <p>You can achieve this by installing the plugin in editable mode. To do this, specify the dependencies in <code>tool.pdm.plugins</code> array:</p> <pre><code>[tool.pdm]\nplugins = [\n\"-e file:///${PROJECT_ROOT}\"\n]\n</code></pre> <p>Then install it with:</p> <pre><code>pdm install --plugins\n</code></pre> <p>After that, all the dependencies are available in a project plugin library, including the plugin itself, in editable mode. That means any change to the codebase will take effect immediately without re-installation. The <code>pdm</code> executable also uses a Python interpreter under the hood, so if you run <code>pdm</code> from inside the plugin project, the plugin in development will be activated automatically, and you can do some testing to see how it works.</p>"},{"location":"dev/write/#testing-your-plugin","title":"Testing your plugin","text":"<p>PDM exposes some pytest fixtures as a plugin in the <code>pdm.pytest</code> module. To benefit from them, you must add <code>pdm[pytest]</code> as a test dependency.</p> <p>To enable them in your test, add <code>pdm.pytest</code> as a plugin. You can do so by in your root <code>conftest.py</code>:</p> conftest.py<pre><code># single plugin\npytest_plugins = \"pytest.plugin\"\n\n# many plugins\npytest_plugins = [\n    ...\n    \"pdm.pytest\",\n    ...\n]\n</code></pre> <p>You can see some usage examples into PDM own tests, especially the conftest.py file for configuration.</p> <p>See the pytest fixtures documentation for more details.</p>"},{"location":"dev/write/#publish-your-plugin","title":"Publish your plugin","text":"<p>Now you have defined your plugin already, let's distribute it to PyPI. PDM's plugins are discovered by entry point types. Create an <code>pdm</code> entry point and point to your plugin callable (yeah, it doesn't need to be a function, any callable object can work):</p> <p>PEP 621:</p> <pre><code># pyproject.toml\n\n[project.entry-points.pdm]\nhello = \"my_plugin:hello_plugin\"\n</code></pre> <p>setuptools:</p> <pre><code># setup.py\n\nsetup(\n    ...\n    entry_points={\"pdm\": [\"hello = my_plugin:hello_plugin\"]}\n    ...\n)\n</code></pre>"},{"location":"dev/write/#activate-the-plugin","title":"Activate the plugin","text":"<p>As plugins are loaded via entry points, they can be activated with no more steps than just installing the plugin. For convenience, PDM provides a <code>plugin</code> command group to manage plugins.</p> <p>Assume your plugin is published as <code>pdm-hello</code>:</p> <pre><code>pdm self add pdm-hello\n</code></pre> <p>Now type <code>pdm --help</code> in the terminal, you will see the new added <code>hello</code> command and use it:</p> <pre><code>$ pdm hello Jack\nHello, Jack\n</code></pre> <p>See more plugin management subcommands by typing <code>pdm self --help</code> in the terminal.</p>"},{"location":"dev/write/#specify-the-plugins-in-project","title":"Specify the plugins in project","text":"<p>To specify the required plugins for a project, you can use the <code>tool.pdm.plugins</code> config in the <code>pyproject.toml</code> file. These dependencies can be installed into a project plugin library by running <code>pdm install --plugins</code>. The project plugin library will be loaded in subsequent PDM commands.</p> <p>This is useful when you want to share the same plugin set with the contributors.</p> <pre><code># pyproject.toml\n[tool.pdm]\nplugins = [\n\"pdm-packer\"\n]\n</code></pre> <p>Run <code>pdm install --plugins</code> to install and activate the plugins.</p> <p>Alternatively, you can have project-local plugins that are not published to PyPI, by using editable local dependencies:</p> <pre><code># pyproject.toml\n[tool.pdm]\nplugins = [\n\"-e file:///${PROJECT_ROOT}/plugins/my_plugin\"\n]\n</code></pre>"},{"location":"reference/api/","title":"API Reference","text":""},{"location":"reference/api/#pdm.core.Core","title":"<code>pdm.core.Core</code>","text":"<p>A high level object that manages all classes and configurations</p>"},{"location":"reference/api/#pdm.core.Core.add_config","title":"<code>add_config(name, config_item)</code>  <code>staticmethod</code>","text":"<p>Add a config item to the configuration class.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name of the config item</p> required <code>config_item</code> <code>pdm.project.config.ConfigItem</code> <p>The config item to add</p> required"},{"location":"reference/api/#pdm.core.Core.create_project","title":"<code>create_project(root_path=None, is_global=False, global_config=None)</code>","text":"<p>Create a new project object</p> <p>Parameters:</p> Name Type Description Default <code>root_path</code> <code>PathLike</code> <p>The path to the project root directory</p> <code>None</code> <code>is_global</code> <code>bool</code> <p>Whether the project is a global project</p> <code>False</code> <code>global_config</code> <code>str</code> <p>The path to the global config file</p> <code>None</code> <p>Returns:</p> Type Description <code>Project</code> <p>The project object</p>"},{"location":"reference/api/#pdm.core.Core.handle","title":"<code>handle(project, options)</code>","text":"<p>Called before command invocation</p>"},{"location":"reference/api/#pdm.core.Core.load_plugins","title":"<code>load_plugins()</code>","text":"<p>Import and load plugins under <code>pdm.plugin</code> namespace A plugin is a callable that accepts the core object as the only argument.</p> Example <pre><code>def my_plugin(core: pdm.core.Core) -&gt; None:\n    ...\n</code></pre>"},{"location":"reference/api/#pdm.core.Core.main","title":"<code>main(args=None, prog_name=None, obj=None, **extra)</code>","text":"<p>The main entry function</p>"},{"location":"reference/api/#pdm.core.Core.register_command","title":"<code>register_command(command, name=None)</code>","text":"<p>Register a subcommand to the subparsers, with an optional name of the subcommand.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>Type[pdm.cli.commands.base.BaseCommand]</code> <p>The command class to register</p> required <code>name</code> <code>str</code> <p>The name of the subcommand, if not given, <code>command.name</code> is used</p> <code>None</code>"},{"location":"reference/api/#pdm.core.Project","title":"<code>pdm.core.Project</code>","text":"<p>Core project class.</p> <p>Parameters:</p> Name Type Description Default <code>core</code> <code>Core</code> <p>The core instance.</p> required <code>root_path</code> <code>str | Path | None</code> <p>The root path of the project.</p> required <code>is_global</code> <code>bool</code> <p>Whether the project is global.</p> <code>False</code> <code>global_config</code> <code>str | Path | None</code> <p>The path to the global config file.</p> <code>None</code>"},{"location":"reference/api/#pdm.project.core.Project.config","title":"<code>config: Mapping[str, Any]</code>  <code>property</code> <code>cached</code>","text":"<p>A read-only dict configuration</p>"},{"location":"reference/api/#pdm.project.core.Project.default_source","title":"<code>default_source: RepositoryConfig</code>  <code>property</code>","text":"<p>Get the default source from the pypi setting</p>"},{"location":"reference/api/#pdm.project.core.Project.project_config","title":"<code>project_config: Config</code>  <code>property</code> <code>cached</code>","text":"<p>Read-and-writable configuration dict for project settings</p>"},{"location":"reference/api/#pdm.project.core.Project.find_interpreters","title":"<code>find_interpreters(python_spec=None, search_venv=None)</code>","text":"<p>Return an iterable of interpreter paths that matches the given specifier,</p> which can be <ol> <li>a version specifier like 3.7</li> <li>an absolute path</li> <li>a short name like python3</li> <li>None that returns all possible interpreters</li> </ol>"},{"location":"reference/api/#pdm.project.core.Project.get_provider","title":"<code>get_provider(strategy='all', tracked_names=None, for_install=False, ignore_compatibility=True, direct_minimal_versions=False)</code>","text":"<p>Build a provider class for resolver.</p> <p>:param strategy: the resolve strategy :param tracked_names: the names of packages that needs to update :param for_install: if the provider is for install :param ignore_compatibility: if the provider should ignore the compatibility when evaluating candidates :param direct_minimal_versions: if the provider should prefer minimal versions instead of latest :returns: The provider object</p>"},{"location":"reference/api/#pdm.project.core.Project.get_reporter","title":"<code>get_reporter(requirements, tracked_names=None, spinner=None)</code>","text":"<p>Return the reporter object to construct a resolver.</p> <p>:param requirements: requirements to resolve :param tracked_names: the names of packages that needs to update :param spinner: optional spinner object :returns: a reporter</p>"},{"location":"reference/api/#pdm.project.core.Project.get_repository","title":"<code>get_repository(cls=None, ignore_compatibility=True)</code>","text":"<p>Get the repository object</p>"},{"location":"reference/api/#pdm.project.core.Project.resolve_interpreter","title":"<code>resolve_interpreter()</code>","text":"<p>Get the Python interpreter path.</p>"},{"location":"reference/api/#pdm.project.core.Project.use_pyproject_dependencies","title":"<code>use_pyproject_dependencies(group, dev=False)</code>","text":"<p>Get the dependencies array and setter in the pyproject.toml Return a tuple of two elements, the first is the dependencies array, and the second value is a callable to set the dependencies array back.</p>"},{"location":"reference/api/#pdm.project.core.Project.write_lockfile","title":"<code>write_lockfile(toml_data, show_message=True, write=True, **_kwds)</code>","text":"<p>Write the lock file to disk.</p>"},{"location":"reference/api/#signals","title":"Signals","text":"<p>Added in version 1.12.0</p> <p>The signal definition for PDM.</p> Example <pre><code>from pdm.signals import post_init, post_install\n\ndef on_post_init(project):\n    project.core.ui.echo(\"Project initialized\")\n# Connect to the signal\npost_init.connect(on_post_init)\n# Or use as a decorator\n@post_install.connect\ndef on_post_install(project, candidates, dry_run):\n    project.core.ui.echo(\"Project install succeeded\")\n</code></pre>"},{"location":"reference/api/#pdm.signals.post_build","title":"<code>post_build: NamedSignal = pdm_signals.signal('post_build')</code>  <code>module-attribute</code>","text":"<p>Called after a project is built.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>artifacts</code> <code>Sequence[str]</code> <p>The locations of built artifacts</p> required <code>config_settings</code> <code>dict[str, str] | None</code> <p>Additional config settings passed via args</p> required"},{"location":"reference/api/#pdm.signals.post_init","title":"<code>post_init: NamedSignal = pdm_signals.signal('post_init')</code>  <code>module-attribute</code>","text":"<p>Called after a project is initialized.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required"},{"location":"reference/api/#pdm.signals.post_install","title":"<code>post_install: NamedSignal = pdm_signals.signal('post_install')</code>  <code>module-attribute</code>","text":"<p>Called after a project is installed.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>candidates</code> <code>dict[str, Candidate]</code> <p>The candidates installed</p> required <code>dry_run</code> <code>bool</code> <p>If true, won't perform any actions</p> required"},{"location":"reference/api/#pdm.signals.post_lock","title":"<code>post_lock: NamedSignal = pdm_signals.signal('post_lock')</code>  <code>module-attribute</code>","text":"<p>Called after a project is locked.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>resolution</code> <code>dict[str, Candidate]</code> <p>The resolved candidates</p> required <code>dry_run</code> <code>bool</code> <p>If true, won't perform any actions</p> required"},{"location":"reference/api/#pdm.signals.post_publish","title":"<code>post_publish: NamedSignal = pdm_signals.signal('post_publish')</code>  <code>module-attribute</code>","text":"<p>Called after a project is published.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required"},{"location":"reference/api/#pdm.signals.post_run","title":"<code>post_run: NamedSignal = pdm_signals.signal('post_run')</code>  <code>module-attribute</code>","text":"<p>Called after any run.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>script</code> <code>str</code> <p>the script name</p> required <code>args</code> <code>Sequence[str]</code> <p>the command line provided arguments</p> required"},{"location":"reference/api/#pdm.signals.post_script","title":"<code>post_script: NamedSignal = pdm_signals.signal('post_script')</code>  <code>module-attribute</code>","text":"<p>Called after any script.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>script</code> <code>str</code> <p>the script name</p> required <code>args</code> <code>Sequence[str]</code> <p>the command line provided arguments</p> required"},{"location":"reference/api/#pdm.signals.post_use","title":"<code>post_use: NamedSignal = pdm_signals.signal('post_use')</code>  <code>module-attribute</code>","text":"<p>Called after use switched to a new Python version.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>python</code> <code>PythonInfo</code> <p>Information about the new Python interpreter</p> required"},{"location":"reference/api/#pdm.signals.pre_build","title":"<code>pre_build: NamedSignal = pdm_signals.signal('pre_build')</code>  <code>module-attribute</code>","text":"<p>Called before a project is built.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>dest</code> <code>str</code> <p>The destination location</p> required <code>config_settings</code> <code>dict[str, str] | None</code> <p>Additional config settings passed via args</p> required"},{"location":"reference/api/#pdm.signals.pre_install","title":"<code>pre_install: NamedSignal = pdm_signals.signal('pre_install')</code>  <code>module-attribute</code>","text":"<p>Called before a project is installed.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>candidates</code> <code>dict[str, Candidate]</code> <p>The candidates to install</p> required <code>dry_run</code> <code>bool</code> <p>If true, won't perform any actions</p> required"},{"location":"reference/api/#pdm.signals.pre_invoke","title":"<code>pre_invoke: NamedSignal = pdm_signals.signal('pre_invoke')</code>  <code>module-attribute</code>","text":"<p>Called before any command is invoked.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>command</code> <code>str | None</code> <p>the command name</p> required <code>options</code> <code>Namespace</code> <p>the parsed arguments</p> required"},{"location":"reference/api/#pdm.signals.pre_lock","title":"<code>pre_lock: NamedSignal = pdm_signals.signal('pre_lock')</code>  <code>module-attribute</code>","text":"<p>Called before a project is locked.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>requirements</code> <code>list[Requirement]</code> <p>The requirements to lock</p> required <code>dry_run</code> <code>bool</code> <p>If true, won't perform any actions</p> required"},{"location":"reference/api/#pdm.signals.pre_publish","title":"<code>pre_publish: NamedSignal = pdm_signals.signal('pre_publish')</code>  <code>module-attribute</code>","text":"<p>Called before a project is published.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required"},{"location":"reference/api/#pdm.signals.pre_run","title":"<code>pre_run: NamedSignal = pdm_signals.signal('pre_run')</code>  <code>module-attribute</code>","text":"<p>Called before any run.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>script</code> <code>str</code> <p>the script name</p> required <code>args</code> <code>Sequence[str]</code> <p>the command line provided arguments</p> required"},{"location":"reference/api/#pdm.signals.pre_script","title":"<code>pre_script: NamedSignal = pdm_signals.signal('pre_script')</code>  <code>module-attribute</code>","text":"<p>Called before any script.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>script</code> <code>str</code> <p>the script name</p> required <code>args</code> <code>Sequence[str]</code> <p>the command line provided arguments</p> required"},{"location":"reference/build/","title":"Build Configuration","text":"<p><code>pdm</code> uses the PEP 517 to build the package. It acts as a build frontend that calls the build backend to build the package.</p> <p>A build backend is what drives the build system to build source distributions and wheels from arbitrary source trees.</p> <p>If you run <code>pdm init</code>, PDM will let you choose the build backend to use. Unlike other package managers, PDM does not force you to use a specific build backend. You can choose the one you like. Here is a list of build backends and corresponding configurations initially supported by PDM:</p> pdm-backendsetuptoolsflithatchlingmaturin <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"pdm-backend\"]\nbuild-backend = \"pdm.backend\"\n</code></pre> <p> Read the docs</p> <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"setuptools\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n</code></pre> <p> Read the docs</p> <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"flit_core &gt;=3.2,&lt;4\"]\nbuild-backend = \"flit_core.buildapi\"\n</code></pre> <p> Read the docs</p> <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n</code></pre> <p> Read the docs</p> <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"maturin&gt;=1.4,&lt;2.0\"]\nbuild-backend = \"maturin\"\n</code></pre> <p> Read the docs</p> <p>Apart from the above mentioned backends, you can also use any other backend that supports PEP 621, however, poetry-core is not supported because it does not support reading PEP 621 metadata.</p> <p>Info</p> <p>If you are using a custom build backend that is not in the above list, PDM will handle the relative paths as PDM-style(<code>${PROJECT_ROOT}</code> variable).</p>"},{"location":"reference/cli/","title":"CLI Reference","text":""},{"location":"reference/cli/#pdm","title":"pdm","text":"<p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-V</code>, <code>--version</code>: Show the version and exit</li> <li><code>-c</code>, <code>--config</code>: Specify another config file path [env var: <code>PDM_CONFIG_FILE</code>] </li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-I</code>, <code>--ignore-python</code>: Ignore the Python path saved in<code>.pdm-python</code>. [env var: <code>PDM_IGNORE_SAVED_PYTHON</code>]</li> <li><code>--pep582</code> <code>SHELL</code>: Print the command line to be eval'd by the shell</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#add","title":"add","text":"<p>Add package(s) to pyproject.toml and install them</p> <p>Package Arguments:</p> <ul> <li><code>-e</code>, <code>--editable</code>: Specify editable packages</li> <li><code>packages</code>: Specify packages</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--frozen-lockfile</code>, <code>--no-lock</code>: Don't try to create or update the lockfile. [env var: <code>PDM_FROZEN_LOCKFILE</code>]</li> <li><code>--save-compatible</code>: Save compatible version specifiers</li> <li><code>--save-wildcard</code>: Save wildcard version specifiers</li> <li><code>--save-exact</code>: Save exact version specifiers</li> <li><code>--save-minimum</code>: Save minimum version specifiers</li> <li><code>--update-reuse</code>: Reuse pinned versions already present in lock file if possible</li> <li><code>--update-eager</code>: Try to update the packages and their dependencies recursively</li> <li><code>--update-all</code>: Update all dependencies and sub-dependencies</li> <li><code>--update-reuse-installed</code>: Reuse installed packages if possible</li> <li><code>--pre</code>, <code>--prerelease</code>: Allow prereleases to be pinned</li> <li><code>--stable</code>: Only allow stable versions to be pinned (default: <code>True</code>)</li> <li><code>-u</code>, <code>--unconstrained</code>: Ignore the version constraint of packages</li> <li><code>--dry-run</code>: Show the difference only and don't perform any action</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>-d</code>, <code>--dev</code>: Add packages into dev dependencies</li> <li><code>-G</code>, <code>--group</code>: Specify the target dependency group to add into</li> <li><code>--no-sync</code>: Only write<code>pyproject.toml</code> and do not sync the working set (default: <code>False</code>)</li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul>"},{"location":"reference/cli/#build","title":"build","text":"<p>Build artifacts for distribution</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> <li><code>--no-sdist</code>: Don't build source tarballs (default: <code>False</code>)</li> <li><code>--no-wheel</code>: Don't build wheels (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dest</code>: Target directory to put artifacts (default: <code>dist</code>)</li> <li><code>--no-clean</code>: Do not clean the target directory (default: <code>False</code>)</li> </ul>"},{"location":"reference/cli/#cache","title":"cache","text":"<p>Control the caches of PDM</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#clear","title":"clear","text":"<p>Clean all the files under cache directory</p> <p>Positional Arguments:</p> <ul> <li><code>type</code>: Clear the given type of caches</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#remove","title":"remove","text":"<p>Remove files matching the given pattern</p> <p>Positional Arguments:</p> <ul> <li><code>pattern</code>: The pattern to remove</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#list","title":"list","text":"<p>List the built wheels stored in the cache</p> <p>Positional Arguments:</p> <ul> <li><code>pattern</code>: The pattern to list (default: <code>*</code>)</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#info","title":"info","text":"<p>Show the info and current size of caches</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#completion","title":"completion","text":"<p>Generate completion scripts for the given shell</p> <p>Positional Arguments:</p> <ul> <li><code>shell</code>: The shell to generate the scripts for. If not given, PDM will properly guess from <code>SHELL</code> env var.</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> </ul>"},{"location":"reference/cli/#config","title":"config","text":"<p>Display the current configuration</p> <p>Positional Arguments:</p> <ul> <li><code>key</code>: Config key</li> <li><code>value</code>: Config value</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-l</code>, <code>--local</code>: Set config in the project's local configuration file</li> <li><code>-d</code>, <code>--delete</code>: Unset a configuration key</li> <li><code>-e</code>, <code>--edit</code>: Edit the configuration file in the default editor(defined by EDITOR env var)</li> </ul>"},{"location":"reference/cli/#export","title":"export","text":"<p>Export the locked packages set to other formats</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>-f</code>, <code>--format</code>: Specify the export file format (default: <code>requirements</code>)</li> <li><code>--no-hashes</code>, <code>--without-hashes</code>: Don't include artifact hashes (default: <code>False</code>)</li> <li><code>--no-markers</code>: Don't include platform markers (default: <code>False</code>)</li> <li><code>-o</code>, <code>--output</code>: Write output to the given file, or print to stdout if not given</li> <li><code>--pyproject</code>: Read the list of packages from<code>pyproject.toml</code></li> <li><code>--expandvars</code>: Expand environment variables in requirements</li> <li><code>--self</code>: Include the project itself</li> <li><code>--editable-self</code>: Include the project itself as an editable dependency</li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies (default: <code>True</code>)</li> </ul>"},{"location":"reference/cli/#fix","title":"fix","text":"<p>Fix the project problems according to the latest version of PDM</p> <p>Positional Arguments:</p> <ul> <li><code>problem</code>: Fix the specific problem, or all if not given</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--dry-run</code>: Only show the problems</li> </ul>"},{"location":"reference/cli/#import","title":"import","text":"<p>Import project metadata from other formats</p> <p>Positional Arguments:</p> <ul> <li><code>filename</code>: The file name</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-d</code>, <code>--dev</code>: import packages into dev dependencies</li> <li><code>-G</code>, <code>--group</code>: Specify the target dependency group to import into</li> <li><code>-f</code>, <code>--format</code>: Specify the file format explicitly</li> </ul>"},{"location":"reference/cli/#info_1","title":"info","text":"<p>Show the project information</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>--python</code>: Show the interpreter path</li> <li><code>--where</code>: Show the project root path</li> <li><code>--packages</code>: Show the local packages root</li> <li><code>--env</code>: Show PEP 508 environment markers</li> <li><code>--json</code>: Dump the information in JSON</li> </ul>"},{"location":"reference/cli/#init","title":"init","text":"<p>Initialize a pyproject.toml for PDM</p> <p>Positional Arguments:</p> <ul> <li><code>template</code>: Specify the project template, which can be a local path or a Git URL</li> <li><code>generator_args</code>: Arguments passed to the generator</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--copier</code>: Use Copier to generate project [not installed] (default: <code>builtin</code>)</li> <li><code>--cookiecutter</code>: Use Cookiecutter to generate project [not installed] (default: <code>builtin</code>)</li> <li><code>-r</code>, <code>--overwrite</code>: Overwrite existing files</li> </ul> <p>Builtin Generator Options:</p> <ul> <li><code>-n</code>, <code>--non-interactive</code>: Don't ask questions but use default values</li> <li><code>--python</code>: Specify the Python version/path to use</li> <li><code>--dist</code>, <code>--lib</code>: Create a package for distribution</li> <li><code>--backend</code>: Specify the build backend, which implies --dist</li> </ul>"},{"location":"reference/cli/#install","title":"install","text":"<p>Install dependencies from lock file</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--dry-run</code>: Show the difference only and don't perform any action</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--frozen-lockfile</code>, <code>--no-lock</code>: Don't try to create or update the lockfile. [env var: <code>PDM_FROZEN_LOCKFILE</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>--check</code>: Check if the lock file is up to date and fail otherwise</li> <li><code>--plugins</code>: Install the plugins specified in<code>pyproject.toml</code></li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies (default: <code>True</code>)</li> </ul>"},{"location":"reference/cli/#list_1","title":"list","text":"<p>List packages installed in the current working set</p> <p>Positional Arguments:</p> <ul> <li><code>patterns</code>: Filter packages by patterns. e.g. pdm list requests- flask-. In --tree mode, only show the subtree of the matched packages.</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>--freeze</code>: Show the installed dependencies in pip's requirements.txt format</li> <li><code>--tree</code>, <code>--graph</code>: Display a tree of dependencies</li> <li><code>-r</code>, <code>--reverse</code>: Reverse the dependency tree</li> <li><code>--resolve</code>: Resolve all requirements to output licenses (instead of just showing those currently installed)</li> <li><code>--fields</code>: Select information to output as a comma separated string. All fields: groups,homepage,licenses,location,name,version. (default: <code>name,version,location</code>)</li> <li><code>--sort</code>: Sort the output using a given field name. If nothing is set, no sort is applied. Multiple fields can be combined with ','.</li> <li><code>--csv</code>: Output dependencies in CSV document format</li> <li><code>--json</code>: Output dependencies in JSON document format</li> <li><code>--markdown</code>: Output dependencies and legal notices in markdown document format - best effort basis</li> <li><code>--include</code>: Dependency groups to include in the output. By default all are included</li> <li><code>--exclude</code>: Exclude dependency groups from the output</li> </ul>"},{"location":"reference/cli/#lock","title":"lock","text":"<p>Resolve and lock dependencies</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--refresh</code>: Don't update pinned versions, only refresh the lock file</li> <li><code>--check</code>: Check if the lock file is up to date and quit</li> <li><code>--update-reuse</code>: Reuse pinned versions already present in lock file if possible (default: <code>all</code>)</li> <li><code>--update-reuse-installed</code>: Reuse installed packages if possible</li> </ul> <p>Lock Strategy:</p> <ul> <li><code>--strategy</code>, <code>-S</code> <code>STRATEGY</code>: Specify lock strategy (cross_platform, static_urls, direct_minimal_versions, inherit_metadata). Add 'no_' prefix to disable. Can be supplied multiple times or split by comma.</li> <li><code>--no-cross-platform</code>: [DEPRECATED] Only lock packages for the current platform</li> <li><code>--static-urls</code>: [DEPRECATED] Store static file URLs in the lockfile</li> <li><code>--no-static-urls</code>: [DEPRECATED] Do not store static file URLs in the lockfile</li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies (default: <code>True</code>)</li> </ul>"},{"location":"reference/cli/#publish","title":"publish","text":"<p>Build and publish the project to PyPI</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>-r</code>, <code>--repository</code>: The repository name or url to publish the package to [env var: <code>PDM_PUBLISH_REPO</code>]</li> <li><code>-u</code>, <code>--username</code>: The username to access the repository [env var: <code>PDM_PUBLISH_USERNAME</code>]</li> <li><code>-P</code>, <code>--password</code>: The password to access the repository [env var: <code>PDM_PUBLISH_PASSWORD</code>]</li> <li><code>-S</code>, <code>--sign</code>: Upload the package with PGP signature</li> <li><code>-i</code>, <code>--identity</code>: GPG identity used to sign files.</li> <li><code>-c</code>, <code>--comment</code>: The comment to include with the distribution file.</li> <li><code>--no-build</code>: Don't build the package before publishing (default: <code>False</code>)</li> <li><code>--skip-existing</code>: Skip uploading files that already exist. This may not work with some repository implementations.</li> <li><code>--no-very-ssl</code>: Disable SSL verification</li> <li><code>--ca-certs</code>: The path to a PEM-encoded Certificate Authority bundle to use for publish server validation [env var: <code>PDM_PUBLISH_CA_CERTS</code>]</li> </ul>"},{"location":"reference/cli/#remove_1","title":"remove","text":"<p>Remove packages from pyproject.toml</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify the packages to remove</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--dry-run</code>: Show the difference only and don't perform any action</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--frozen-lockfile</code>, <code>--no-lock</code>: Don't try to create or update the lockfile. [env var: <code>PDM_FROZEN_LOCKFILE</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-d</code>, <code>--dev</code>: Remove packages from dev dependencies</li> <li><code>-G</code>, <code>--group</code>: Specify the target dependency group to remove from</li> <li><code>--no-sync</code>: Only write<code>pyproject.toml</code> and do not uninstall packages (default: <code>False</code>)</li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul>"},{"location":"reference/cli/#run","title":"run","text":"<p>Run commands or scripts with local packages loaded</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-l</code>, <code>--list</code>: Show all available scripts defined in<code>pyproject.toml</code></li> <li><code>-j</code>, <code>--json</code>: Output all scripts infos in JSON</li> </ul> <p>Execution Parameters:</p> <ul> <li><code>-s</code>, <code>--site-packages</code>: Load site-packages from the selected interpreter</li> <li><code>script</code>: The command to run</li> <li><code>args</code>: Arguments that will be passed to the command</li> </ul>"},{"location":"reference/cli/#search","title":"search","text":"<p>Search for PyPI packages</p> <p>Positional Arguments:</p> <ul> <li><code>query</code>: Query string to search</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#self","title":"self","text":"<p>Manage the PDM program itself (previously known as plugin)</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#list_2","title":"list","text":"<p>List all packages installed with PDM</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--plugins</code>: List plugins only</li> </ul>"},{"location":"reference/cli/#add_1","title":"add","text":"<p>Install packages to the PDM's environment</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify one or many package names, each package can have a version specifier</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--pip-args</code>: Arguments that will be passed to pip install</li> </ul>"},{"location":"reference/cli/#remove_2","title":"remove","text":"<p>Remove packages from PDM's environment</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify one or many package names</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--pip-args</code>: Arguments that will be passed to pip uninstall</li> <li><code>-y</code>, <code>--yes</code>: Answer yes on the question</li> </ul>"},{"location":"reference/cli/#update","title":"update","text":"<p>Update PDM itself</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--head</code>: Update to the latest commit on the main branch</li> <li><code>--pre</code>: Update to the latest prerelease version</li> <li><code>--pip-args</code>: Additional arguments that will be passed to pip install</li> </ul>"},{"location":"reference/cli/#plugin","title":"plugin","text":"<p>Manage the PDM program itself (previously known as plugin)</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#list_3","title":"list","text":"<p>List all packages installed with PDM</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--plugins</code>: List plugins only</li> </ul>"},{"location":"reference/cli/#add_2","title":"add","text":"<p>Install packages to the PDM's environment</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify one or many package names, each package can have a version specifier</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--pip-args</code>: Arguments that will be passed to pip install</li> </ul>"},{"location":"reference/cli/#remove_3","title":"remove","text":"<p>Remove packages from PDM's environment</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify one or many package names</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--pip-args</code>: Arguments that will be passed to pip uninstall</li> <li><code>-y</code>, <code>--yes</code>: Answer yes on the question</li> </ul>"},{"location":"reference/cli/#update_1","title":"update","text":"<p>Update PDM itself</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--head</code>: Update to the latest commit on the main branch</li> <li><code>--pre</code>: Update to the latest prerelease version</li> <li><code>--pip-args</code>: Additional arguments that will be passed to pip install</li> </ul>"},{"location":"reference/cli/#show","title":"show","text":"<p>Show the package information</p> <p>Positional Arguments:</p> <ul> <li><code>package</code>: Specify the package name, or show this package if not given</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>--name</code>: Show name</li> <li><code>--version</code>: Show version</li> <li><code>--summary</code>: Show summary</li> <li><code>--license</code>: Show license</li> <li><code>--platform</code>: Show platform</li> <li><code>--keywords</code>: Show keywords</li> </ul>"},{"location":"reference/cli/#sync","title":"sync","text":"<p>Synchronize the current working set with lock file</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--dry-run</code>: Show the difference only and don't perform any action</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--clean</code>: Clean packages not in the lockfile</li> <li><code>--only-keep</code>: Only keep the selected packages</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-r</code>, <code>--reinstall</code>: Force reinstall existing dependencies</li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies (default: <code>True</code>)</li> </ul>"},{"location":"reference/cli/#update_2","title":"update","text":"<p>Update package(s) in pyproject.toml</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: If packages are given, only update them</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--frozen-lockfile</code>, <code>--no-lock</code>: Don't try to create or update the lockfile. [env var: <code>PDM_FROZEN_LOCKFILE</code>]</li> <li><code>--save-compatible</code>: Save compatible version specifiers</li> <li><code>--save-wildcard</code>: Save wildcard version specifiers</li> <li><code>--save-exact</code>: Save exact version specifiers</li> <li><code>--save-minimum</code>: Save minimum version specifiers</li> <li><code>--update-reuse</code>: Reuse pinned versions already present in lock file if possible</li> <li><code>--update-eager</code>: Try to update the packages and their dependencies recursively</li> <li><code>--update-all</code>: Update all dependencies and sub-dependencies</li> <li><code>--update-reuse-installed</code>: Reuse installed packages if possible</li> <li><code>--pre</code>, <code>--prerelease</code>: Allow prereleases to be pinned</li> <li><code>--stable</code>: Only allow stable versions to be pinned (default: <code>True</code>)</li> <li><code>-u</code>, <code>--unconstrained</code>: Ignore the version constraint of packages</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-t</code>, <code>--top</code>: Only update those listed in<code>pyproject.toml</code></li> <li><code>--dry-run</code>, <code>--outdated</code>: Show the difference only without modifying the lockfile content</li> <li><code>--no-sync</code>: Only update lock file but do not sync packages (default: <code>False</code>)</li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies</li> </ul>"},{"location":"reference/cli/#use","title":"use","text":"<p>Use the given python version or path as base interpreter</p> <p>Positional Arguments:</p> <ul> <li><code>python</code>: Specify the Python version or path</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>-f</code>, <code>--first</code>: Select the first matched interpreter</li> <li><code>-i</code>, <code>--ignore-remembered</code>: Ignore the remembered selection</li> <li><code>--venv</code>: Use the interpreter in the virtual environment with the given name</li> </ul>"},{"location":"reference/cli/#venv","title":"venv","text":"<p>Virtualenv management</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--path</code>: Show the path to the given virtualenv</li> <li><code>--python</code>: Show the python interpreter path for the given virtualenv</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#create","title":"create","text":"<p>Create a virtualenv</p> <p>Positional Arguments:</p> <ul> <li><code>python</code>: Specify which python should be used to create the virtualenv</li> <li><code>venv_args</code>: Additional arguments that will be passed to the backend</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-w</code>, <code>--with</code>: Specify the backend to create the virtualenv</li> <li><code>-f</code>, <code>--force</code>: Recreate if the virtualenv already exists</li> <li><code>-n</code>, <code>--name</code>: Specify the name of the virtualenv</li> <li><code>--with-pip</code>: Install pip with the virtualenv</li> </ul>"},{"location":"reference/cli/#list_4","title":"list","text":"<p>List all virtualenvs associated with this project</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#remove_4","title":"remove","text":"<p>Remove the virtualenv with the given name</p> <p>Positional Arguments:</p> <ul> <li><code>env</code>: The key of the virtualenv</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-y</code>, <code>--yes</code>: Answer yes on the following question</li> </ul>"},{"location":"reference/cli/#activate","title":"activate","text":"<p>Print the command to activate the virtualenv with the given name</p> <p>Positional Arguments:</p> <ul> <li><code>env</code>: The key of the virtualenv</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#purge","title":"purge","text":"<p>Purge selected/all created Virtualenvs</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-f</code>, <code>--force</code>: Force purging without prompting for confirmation</li> <li><code>-i</code>, <code>--interactive</code>: Interactively purge selected Virtualenvs</li> </ul>"},{"location":"reference/configuration/","title":"Configurations","text":""},{"location":"reference/configuration/#color-theme","title":"Color Theme","text":"<p>The default theme used by PDM is as follows:</p> Key Default Style <code>primary</code> cyan <code>success</code> green <code>warning</code> yellow <code>error</code> red <code>info</code> blue <code>req</code> bold green <p>You can change the theme colors with <code>pdm config</code> command. For example, to change the <code>primary</code> color to <code>magenta</code>:</p> <pre><code>pdm config theme.primary magenta\n</code></pre> <p>Or use a hex color code:</p> <pre><code>pdm config theme.success '#51c7bd'\n</code></pre>"},{"location":"reference/configuration/#available-configurations","title":"Available Configurations","text":"<p>The following configuration items can be retrieved and modified by <code>pdm config</code> command.</p> <p>Environment Variable Overrides</p> <p>If the corresponding env var is set, the value will take precedence over what is saved in the config file.</p> Config Item Description Default Value Available in Project Env var <code>cache_dir</code> The root directory of cached files <code>/home/runner/.cache/pdm</code> No <code>PDM_CACHE_DIR</code> <code>log_dir</code> The root directory of log files <code>/home/runner/.local/state/pdm/log</code> No <code>PDM_LOG_DIR</code> <code>check_update</code> Check if there is any newer version available <code>True</code> No <code>PDM_CHECK_UPDATE</code> <code>build_isolation</code> Isolate build environment from the project environment <code>True</code> Yes <code>PDM_BUILD_ISOLATION</code> <code>request_timeout</code> The timeout for network requests in seconds <code>15</code> No <code>PDM_REQUEST_TIMEOUT</code> <code>global_project.fallback</code> Use the global project implicitly if no local project is found <code>False</code> No <code>global_project.fallback_verbose</code> If True show message when global project is used implicitly <code>True</code> No <code>global_project.path</code> The path to the global project <code>/home/runner/.config/pdm/global-project</code> No <code>global_project.user_site</code> Whether to install to user site <code>False</code> No <code>strategy.update</code> The default strategy for updating packages <code>reuse</code> Yes <code>strategy.save</code> Specify how to save versions when a package is added <code>minimum</code> Yes <code>strategy.resolve_max_rounds</code> Specify the max rounds of resolution process <code>10000</code> Yes <code>PDM_RESOLVE_MAX_ROUNDS</code> <code>strategy.inherit_metadata</code> Inherit the groups and markers from parents for each package <code>True</code> Yes <code>install.parallel</code> Whether to perform installation and uninstallation in parallel <code>True</code> Yes <code>PDM_INSTALL_PARALLEL</code> <code>install.cache</code> Cache wheel installation and only put symlinks in the library root <code>False</code> Yes <code>install.cache_method</code> Specify how to create links to the caches(<code>symlink/hardlink</code>) <code>symlink</code> Yes <code>python.providers</code> List of python provider names for findpython <code>[]</code> Yes <code>python.use_pyenv</code> Use the pyenv interpreter <code>True</code> Yes <code>python.use_venv</code> Use virtual environments when available <code>True</code> Yes <code>PDM_USE_VENV</code> <code>pypi.url</code> The URL of PyPI mirror, defaults to https://pypi.org/simple <code>https://pypi.org/simple</code> Yes <code>PDM_PYPI_URL</code> <code>pypi.verify_ssl</code> Verify SSL certificate when query PyPI <code>True</code> Yes <code>pypi.username</code> The username to access PyPI Yes <code>PDM_PYPI_USERNAME</code> <code>pypi.password</code> The password to access PyPI Yes <code>PDM_PYPI_PASSWORD</code> <code>pypi.ca_certs</code> Path to a CA certificate bundle used for verifying the identity of the PyPI server No <code>pypi.ignore_stored_index</code> Ignore the configured indexes <code>False</code> Yes <code>PDM_IGNORE_STORED_INDEX</code> <code>pypi.client_cert</code> Path to client certificate file, or combined cert/key file No <code>pypi.client_key</code> Path to client cert keyfile, if not in pypi.client_cert No <code>pypi.json_api</code> Consult PyPI's JSON API for package metadata <code>False</code> Yes <code>PDM_PYPI_JSON_API</code> <code>venv.location</code> Parent directory for virtualenvs <code>/home/runner/.local/share/pdm/venvs</code> No <code>venv.backend</code> Default backend to create virtualenv <code>virtualenv</code> Yes <code>PDM_VENV_BACKEND</code> <code>venv.in_project</code> Create virtualenv in <code>.venv</code> under project root <code>True</code> Yes <code>PDM_VENV_IN_PROJECT</code> <code>venv.prompt</code> Define a custom template to be displayed in the prompt when virtualenv isactive. Variables <code>project_name</code> and <code>python_version</code> are available forformatting <code>{project_name}-{python_version}</code> Yes <code>PDM_VENV_PROMPT</code> <code>venv.with_pip</code> Install pip when creating a new venv <code>False</code> Yes <code>PDM_VENV_WITH_PIP</code> <code>theme.primary</code> Theme color for primary <code>cyan</code> No <code>theme.success</code> Theme color for success <code>green</code> No <code>theme.warning</code> Theme color for warning <code>yellow</code> No <code>theme.error</code> Theme color for error <code>red</code> No <code>theme.info</code> Theme color for info <code>blue</code> No <code>theme.req</code> Theme color for req <code>bold green</code> No <code>pypi.&lt;name&gt;.url</code> The URL of custom package source <code>https://pypi.org/simple</code> Yes <code>pypi.&lt;name&gt;.username</code> The username to access custom source Yes <code>pypi.&lt;name&gt;.password</code> The password to access custom source Yes <code>pypi.&lt;name&gt;.type</code> <code>index</code> or <code>find_links</code> <code>index</code> Yes <code>pypi.&lt;name&gt;.verify_ssl</code> Verify SSL certificate when query custom source <code>True</code> Yes <code>repository.&lt;name&gt;.url</code> The URL of custom package source <code>https://pypi.org/simple</code> Yes <code>repository.&lt;name&gt;.username</code> The username to access custom repository Yes <code>repository.&lt;name&gt;.password</code> The password to access custom repository Yes <code>repository.&lt;name&gt;.ca_certs</code> Path to a PEM-encoded CA cert bundle (used for server cert verification) The CA certificates from certifi Yes <code>repository.&lt;name&gt;.verify_ssl</code> Verify SSL certificate when uploading to repository <code>True</code> Yes"},{"location":"reference/pep621/","title":"PEP 621 Metadata","text":"<p>The project metadata are stored in the <code>pyproject.toml</code>. The specifications are defined by PEP 621, PEP 631 and PEP 639. Read the detailed specifications in the PEPs.</p> <p>In the following part of this document, metadata should be written under <code>[project]</code> table if not given explicitly.</p>"},{"location":"reference/pep621/#multiline-description","title":"Multiline description","text":"<p>You can split a long description onto multiple lines, thanks to TOML support for multiline strings. Just remember to escape new lines, so the final description appears on one line only in your package metadata. Indentation will be removed as well when escaping new lines:</p> <pre><code>description = \"\"\"\\\n    Lorem ipsum dolor sit amet, consectetur adipiscing elit, \\\n    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. \\\n    Ut enim ad minim veniam, quis nostrud exercitation ullamco \\\n    laboris nisi ut aliquip ex ea commodo consequat.\\\n\"\"\"\n</code></pre> <p>See TOML's specification on strings.</p>"},{"location":"reference/pep621/#package-version","title":"Package version","text":"StaticDynamic <pre><code>[project]\nversion = \"1.0.0\"\n</code></pre> <pre><code>[project]\n...\ndynamic = [\"version\"]\n\n[tool.pdm]\nversion = { source = \"file\", path = \"mypackage/__version__.py\" }\n</code></pre> <p>The version will be read from the <code>mypackage/__version__.py</code> file searching for the pattern: <code>__version__ = \"{version}\"</code>.</p> <p>Read more information about other configurations in dynamic project version from the <code>pdm-backend</code> documentation.</p>"},{"location":"reference/pep621/#python-version","title":"Python version","text":"<p>The required version of Python is specified as the string <code>requires-python</code>:</p> <pre><code>requires-python = \"&gt;=3.9\"\nclassifiers = [\n    \"Programming Language :: Python :: 3\",\n    \"Programming Language :: Python :: 3.9\",\n    \"Programming Language :: Python :: 3.10\",\n    \"Programming Language :: Python :: 3.11\",\n    ...\n]\n</code></pre> <p>Note: As per PEP 621, PDM is not permitted to dynamically update the <code>classifiers</code> section like some other non-compliant tools. Thus, you should also include the appropriate trove classifiers as shown above if you plan on publishing your package on PyPI.</p>"},{"location":"reference/pep621/#license","title":"License","text":"<p>The license is specified as the string <code>license</code>:</p> <pre><code>license = {text = \"BSD-2-Clause\"}\nclassifiers = [\n    \"License :: OSI Approved :: BSD License\",\n    ...\n]\n</code></pre> <p>Note: As per PEP 621, PDM is not permitted to dynamically update the <code>classifiers</code> section like some other non-compliant tools. Thus, you should also include the appropriate trove classifiers as shown above if you plan on publishing your package on PyPI.</p>"},{"location":"reference/pep621/#dependency-specification","title":"Dependency specification","text":"<p>The <code>project.dependencies</code> is an array of dependency specification strings following the PEP 440 and PEP 508.</p> <p>Examples:</p> <pre><code>[project]\n...\ndependencies = [\n# Named requirement\n\"requests\",\n# Named requirement with version specifier\n\"flask &gt;= 1.1.0\",\n# Requirement with environment marker\n\"pywin32; sys_platform == 'win32'\",\n# URL requirement\n\"pip @ git+https://github.com/pypa/pip.git@20.3.1\"\n]\n</code></pre>"},{"location":"reference/pep621/#optional-dependencies","title":"Optional dependencies","text":"<p>You can have some requirements optional, which is similar to <code>setuptools</code>' <code>extras_require</code> parameter.</p> <pre><code>[project.optional-dependencies]\nsocks = [ 'PySocks &gt;= 1.5.6, != 1.5.7, &lt; 2' ]\ntests = [\n'ddt &gt;= 1.2.2, &lt; 2',\n'pytest &lt; 6',\n'mock &gt;= 1.0.1, &lt; 4; python_version &lt; \"3.4\"',\n]\n</code></pre> <p>To install a group of optional dependencies:</p> <pre><code>pdm install -G socks\n</code></pre> <p><code>-G</code> option can be given multiple times to include more than one group.</p>"},{"location":"reference/pep621/#context-variables-expansion","title":"Context variables expansion","text":"<p>Depending on which build backend you are using, PDM will expand some variables in the dependency strings.</p>"},{"location":"reference/pep621/#environment-variables","title":"Environment variables","text":"pdm-backendhatchling <pre><code>[project]\ndependencies = [\"flask @ https://${USERNAME}:${PASSWORD}/artifacts.io/Flask-1.1.2.tar.gz\"]\n</code></pre> <pre><code>[project]\ndependencies = [\"flask @ https://{env:USERNAME}:{env:PASSWORD}/artifacts.io/Flask-1.1.2.tar.gz\"]\n</code></pre> <p>Find more usages here</p> <p>Don't worry about credential leakage, the environment variables will be expanded when needed and kept untouched in the lock file.</p>"},{"location":"reference/pep621/#relative-paths","title":"Relative paths","text":"<p>When you add a package from a relative path, PDM will automatically save it as a relative path for <code>pdm-backend</code> and <code>hatchling</code>.</p> <p>For example, if you run <code>pdm add ./my-package</code>, it will result in the following line in <code>pyproject.toml</code>.</p> pdm-backendhatchling <pre><code>[project]\ndependencies = [\"my-package @ file:///${PROJECT_ROOT}/my-package\"]\n</code></pre> <pre><code>[project]\ndependencies = [\"my-package @ {root:uri}/my-package\"]\n</code></pre> <p>By default, hatchling doesn't support direct references in the dependency string, you need to turn it on in <code>pyproject.toml</code>:</p> <pre><code>[tool.hatch.metadata]\nallow-direct-references = true\n</code></pre> <p>The relative path will be expanded based on the project root when installing or locking.</p>"},{"location":"reference/pep621/#console-scripts","title":"Console scripts","text":"<p>The following content:</p> <pre><code>[project.scripts]\nmycli = \"mycli.__main__:main\"\n</code></pre> <p>will be translated to <code>setuptools</code> style:</p> <pre><code>entry_points = {\n    'console_scripts': [\n        'mycli=mycli.__main__:main'\n    ]\n}\n</code></pre> <p>Also, <code>[project.gui-scripts]</code> will be translated to <code>gui_scripts</code> entry points group in <code>setuptools</code> style.</p>"},{"location":"reference/pep621/#entry-points","title":"Entry points","text":"<p>Other types of entry points are given by <code>[project.entry-points.&lt;type&gt;]</code> section, with the same format of <code>[project.scripts]</code>:</p> <pre><code>[project.entry-points.pytest11]\nmyplugin = \"mypackage.plugin:pytest_plugin\"\n</code></pre> <p>If the entry point name contains dots or other special characters, wrap it in quotes:</p> <pre><code>[project.entry-points.\"flake8.extension\"]\nmyplugin = \"mypackage.plugin:flake8_plugin\"\n</code></pre>"},{"location":"usage/advanced/","title":"Advanced Usage","text":""},{"location":"usage/advanced/#automatic-testing","title":"Automatic Testing","text":""},{"location":"usage/advanced/#use-tox-as-the-runner","title":"Use Tox as the runner","text":"<p>Tox is a great tool for testing against multiple Python versions or dependency sets. You can configure a <code>tox.ini</code> like the following to integrate your testing with PDM:</p> <pre><code>[tox]\nenv_list = py{36,37,38},lint\n\n[testenv]\nsetenv =\nPDM_IGNORE_SAVED_PYTHON=\"1\"\ndeps = pdm\ncommands =\npdm install --dev\npytest tests\n\n[testenv:lint]\ndeps = pdm\ncommands =\npdm install -G lint\nflake8 src/\n</code></pre> <p>To use the virtualenv created by Tox, you should make sure you have set <code>pdm config python.use_venv true</code>. PDM then will install dependencies from <code>pdm lock</code> into the virtualenv. In the dedicated venv you can directly run tools by <code>pytest tests/</code> instead of <code>pdm run pytest tests/</code>.</p> <p>You should also make sure you don't run <code>pdm add/pdm remove/pdm update/pdm lock</code> in the test commands, otherwise the <code>pdm lock</code> file will be modified unexpectedly. Additional dependencies can be supplied with the <code>deps</code> config. Besides, <code>isolated_build</code> and <code>passenv</code> config should be set as the above example to make PDM work properly.</p> <p>To get rid of these constraints, there is a Tox plugin tox-pdm which can ease the usage. You can install it by</p> <pre><code>pip install tox-pdm\n</code></pre> <p>Or,</p> <pre><code>pdm add --dev tox-pdm\n</code></pre> <p>And you can make the <code>tox.ini</code> much tidier as following, :</p> <pre><code>[tox]\nenv_list = py{36,37,38},lint\n\n[testenv]\ngroups = dev\ncommands =\npytest tests\n\n[testenv:lint]\ngroups = lint\ncommands =\nflake8 src/\n</code></pre> <p>See the project's README for a detailed guidance.</p>"},{"location":"usage/advanced/#use-nox-as-the-runner","title":"Use Nox as the runner","text":"<p>Nox is another great tool for automated testing. Unlike tox, Nox uses a standard Python file for configuration.</p> <p>It is much easier to use PDM in Nox, here is an example of <code>noxfile.py</code>:</p> <pre><code>import os\nimport nox\n\nos.environ.update({\"PDM_IGNORE_SAVED_PYTHON\": \"1\"})\n@nox.session\ndef tests(session):\n    session.run_always('pdm', 'install', '-G', 'test', external=True)\n    session.run('pytest')\n\n@nox.session\ndef lint(session):\n    session.run_always('pdm', 'install', '-G', 'lint', external=True)\n    session.run('flake8', '--import-order-style', 'google')\n</code></pre> <p>Note that <code>PDM_IGNORE_SAVED_PYTHON</code> should be set so that PDM can pick up the Python in the virtualenv correctly. Also make sure <code>pdm</code> is available in the <code>PATH</code>. Before running nox, you should also ensure configuration item <code>python.use_venv</code> is true to enable venv reusing.</p>"},{"location":"usage/advanced/#about-pep-582-__pypackages__-directory","title":"About PEP 582 <code>__pypackages__</code> directory","text":"<p>By default, if you run tools by <code>pdm run</code>, <code>__pypackages__</code> will be seen by the program and all subprocesses created by it. This means virtual environments created by those tools are also aware of the packages inside <code>__pypackages__</code>, which result in unexpected behavior in some cases. For <code>nox</code>, you can avoid this by adding a line in <code>noxfile.py</code>:</p> <pre><code>os.environ.pop(\"PYTHONPATH\", None)\n</code></pre> <p>For <code>tox</code>, <code>PYTHONPATH</code> will not be passed to the test sessions so this isn't going to be a problem. Moreover, it is recommended to make <code>nox</code> and <code>tox</code> live in their own pipx environments so you don't need to install for every project. In this case, PEP 582 packages will not be a problem either.</p>"},{"location":"usage/advanced/#use-pdm-in-continuous-integration","title":"Use PDM in Continuous Integration","text":"<p>Only one thing to keep in mind -- PDM can't be installed on Python &lt; 3.7, so if your project is to be tested on those Python versions, you have to make sure PDM is installed on the correct Python version, which can be different from the target Python version the particular job/task is run on.</p> <p>Fortunately, if you are using GitHub Action, there is pdm-project/setup-pdm to make this process easier. Here is an example workflow of GitHub Actions, while you can adapt it for other CI platforms.</p> <pre><code>Testing:\nruns-on: ${{ matrix.os }}\nstrategy:\nmatrix:\npython-version: [3.7, 3.8, 3.9, '3.10', '3.11']\nos: [ubuntu-latest, macOS-latest, windows-latest]\n\nsteps:\n- uses: actions/checkout@v3\n- name: Set up PDM\nuses: pdm-project/setup-pdm@v3\nwith:\npython-version: ${{ matrix.python-version }}\n\n- name: Install dependencies\nrun: |\npdm sync -d -G testing\n- name: Run Tests\nrun: |\npdm run -v pytest tests\n</code></pre> <p>TIPS</p> <p>For GitHub Action users, there is a known compatibility issue on Ubuntu virtual environment. If PDM parallel install is failed on that machine you should either set <code>parallel_install</code> to <code>false</code> or set env <code>LD_PRELOAD=/lib/x86_64-linux-gnu/libgcc_s.so.1</code>. It is already handled by the <code>pdm-project/setup-pdm</code> action.</p> <p>Note</p> <p>If your CI scripts run without a proper user set, you might get permission errors when PDM tries to create its cache directory. To work around this, you can set the HOME environment variable yourself, to a writable directory, for example:</p> <pre><code>export HOME=/tmp/home\n</code></pre>"},{"location":"usage/advanced/#use-pdm-in-a-multi-stage-dockerfile","title":"Use PDM in a multi-stage Dockerfile","text":"<p>It is possible to use PDM in a multi-stage Dockerfile to first install the project and dependencies into <code>__pypackages__</code> and then copy this folder into the final stage, adding it to <code>PYTHONPATH</code>.</p> <pre><code># build stage\nFROM python:3.8 AS builder\n\n# install PDM\nRUN pip install -U pip setuptools wheel\nRUN pip install pdm\n\n# copy files\nCOPY pyproject.toml pdm.lock README.md /project/\nCOPY src/ /project/src\n\n# install dependencies and project into the local packages directory\nWORKDIR /project\nRUN mkdir __pypackages__ &amp;&amp; pdm sync --prod --no-editable\n\n\n# run stage\nFROM python:3.8\n\n# retrieve packages from build stage\nENV PYTHONPATH=/project/pkgs\nCOPY --from=builder /project/__pypackages__/3.8/lib /project/pkgs\n\n# retrieve executables\nCOPY --from=builder /project/__pypackages__/3.8/bin/* /bin/\n\n# set command/entrypoint, adapt to fit your needs\nCMD [\"python\", \"-m\", \"project\"]\n</code></pre>"},{"location":"usage/advanced/#use-pdm-to-manage-a-monorepo","title":"Use PDM to manage a monorepo","text":"<p>With PDM, you can have multiple sub-packages within a single project, each with its own <code>pyproject.toml</code> file. And you can create only one <code>pdm.lock</code> file to lock all dependencies. The sub-packages can have each other as their dependencies. To achieve this, follow these steps:</p> <p><code>project/pyproject.toml</code>:</p> <pre><code>[tool.pdm.dev-dependencies]\ndev = [\n\"-e file:///${PROJECT_ROOT}/packages/foo-core\",\n\"-e file:///${PROJECT_ROOT}/packages/foo-cli\",\n\"-e file:///${PROJECT_ROOT}/packages/foo-app\",\n]\n</code></pre> <p><code>packages/foo-cli/pyproject.toml</code>:</p> <pre><code>[project]\ndependencies = [\"foo-core\"]\n</code></pre> <p><code>packages/foo-app/pyproject.toml</code>:</p> <pre><code>[project]\ndependencies = [\"foo-core\"]\n</code></pre> <p>Now, run <code>pdm install</code> in the project root, and you will get a <code>pdm.lock</code> with all dependencies locked. All sub-packages will be installed in editable mode.</p> <p>Look at the \ud83d\ude80 Example repository for more details.</p>"},{"location":"usage/advanced/#hooks-for-pre-commit","title":"Hooks for <code>pre-commit</code>","text":"<p><code>pre-commit</code> is a powerful framework for managing git hooks in a centralized fashion. PDM already uses <code>pre-commit</code> hooks for its internal QA checks. PDM exposes also several hooks that can be run locally or in CI pipelines.</p>"},{"location":"usage/advanced/#export-requirementstxt","title":"Export <code>requirements.txt</code>","text":"<p>This hook wraps the command <code>pdm export</code> along with any valid argument. It can be used as a hook (e.g., for CI) to ensure that you are going to check in the codebase a <code>requirements.txt</code>, which reflects the actual content of <code>pdm lock</code>.</p> <pre><code># export python requirements\n- repo: https://github.com/pdm-project/pdm\nrev: 2.x.y # a PDM release exposing the hook\nhooks:\n- id: pdm-export\n# command arguments, e.g.:\nargs: ['-o', 'requirements.txt', '--without-hashes']\nfiles: ^pdm.lock$\n</code></pre>"},{"location":"usage/advanced/#check-pdmlock-is-up-to-date-with-pyprojecttoml","title":"Check <code>pdm.lock</code> is up to date with pyproject.toml","text":"<p>This hook wraps the command <code>pdm lock --check</code> along with any valid argument. It can be used as a hook (e.g., for CI) to ensure that whenever <code>pyproject.toml</code> has a dependency added/changed/removed, that <code>pdm.lock</code> is also up to date.</p> <pre><code>- repo: https://github.com/pdm-project/pdm\nrev: 2.x.y # a PDM release exposing the hook\nhooks:\n- id: pdm-lock-check\n</code></pre>"},{"location":"usage/advanced/#sync-current-working-set-with-pdmlock","title":"Sync current working set with <code>pdm.lock</code>","text":"<p>This hook wraps the command <code>pdm sync</code> along with any valid argument. It can be used as a hook to ensure that your current working set is synced with <code>pdm.lock</code> whenever you checkout or merge a branch. Add keyring to <code>additional_dependencies</code> if you want to use your systems credential store.</p> <pre><code>- repo: https://github.com/pdm-project/pdm\nrev: 2.x.y # a PDM release exposing the hook\nhooks:\n- id: pdm-sync\nadditional_dependencies:\n- keyring\n</code></pre>"},{"location":"usage/config/","title":"Configure the Project","text":"<p>PDM's <code>config</code> command works just like <code>git config</code>, except that <code>--list</code> isn't needed to show configurations.</p> <p>Show the current configurations:</p> <pre><code>pdm config\n</code></pre> <p>Get one single configuration:</p> <pre><code>pdm config pypi.url\n</code></pre> <p>Change a configuration value and store in home configuration:</p> <pre><code>pdm config pypi.url \"https://test.pypi.org/simple\"\n</code></pre> <p>By default, the configuration are changed globally, if you want to make the config seen by this project only, add a <code>--local</code> flag:</p> <pre><code>pdm config --local pypi.url \"https://test.pypi.org/simple\"\n</code></pre> <p>Any local configurations will be stored in <code>pdm.toml</code> under the project root directory.</p>"},{"location":"usage/config/#configuration-files","title":"Configuration files","text":"<p>The configuration files are searched in the following order:</p> <ol> <li><code>&lt;PROJECT_ROOT&gt;/pdm.toml</code> - The project configuration</li> <li><code>&lt;CONFIG_ROOT&gt;/config.toml</code> - The home configuration</li> <li><code>&lt;SITE_CONFIG_ROOT&gt;/config.toml</code> - The site configuration</li> </ol> <p>where <code>&lt;CONFIG_ROOT&gt;</code> is:</p> <ul> <li><code>$XDG_CONFIG_HOME/pdm</code> (<code>~/.config/pdm</code> in most cases) on Linux as defined by XDG Base Directory Specification</li> <li><code>~/Library/Application Support/pdm</code> on macOS as defined by Apple File System Basics</li> <li><code>%USERPROFILE%\\AppData\\Local\\pdm</code> on Windows as defined in Known folders</li> </ul> <p>and <code>&lt;SITE_CONFIG_ROOT&gt;</code> is:</p> <ul> <li><code>$XDG_CONFIG_DIRS/pdm</code> (<code>/etc/xdg/pdm</code> in most cases) on Linux as defined by XDG Base Directory Specification</li> <li><code>/Library/Application Support/pdm</code> on macOS as defined by Apple File System Basics</li> <li><code>C:\\ProgramData\\pdm\\pdm</code> on Windows as defined in Known folders</li> </ul> <p>If <code>-g/--global</code> option is used, the first item will be replaced by <code>&lt;CONFIG_ROOT&gt;/global-project/pdm.toml</code>.</p> <p>You can find all available configuration items in Configuration Page.</p>"},{"location":"usage/config/#configure-the-python-finder","title":"Configure the Python finder","text":"<p>By default, PDM will try to find Python interpreters in the following sources:</p> <ul> <li><code>venv</code>: The PDM virtualenv location</li> <li><code>path</code>: The <code>PATH</code> environment variable</li> <li><code>pyenv</code>: The pyenv install root</li> <li><code>rye</code>: The rye toolchain install root</li> <li><code>asdf</code>: The asdf python install root</li> <li><code>winreg</code>: The Windows registry</li> </ul> <p>You can unselect some of them or change the order by setting <code>python.providers</code> config key:</p> <pre><code>pdm config python.providers rye   # Rye source only\npdm config python.providers pyenv,asdf  # pyenv and asdf\n</code></pre>"},{"location":"usage/config/#allow-prereleases-in-resolution-result","title":"Allow prereleases in resolution result","text":"<p>By default, <code>pdm</code>'s dependency resolver will ignore prereleases unless there are no stable versions for the given version range of a dependency. This behavior can be changed by setting <code>allow-prereleases</code> to <code>true</code> in <code>[tool.pdm.resolution]</code> table:</p> <pre><code>[tool.pdm.resolution]\nallow-prereleases = true\n</code></pre>"},{"location":"usage/config/#configure-the-package-indexes","title":"Configure the package indexes","text":"<p>You can tell PDM where to to find the packages by either specifying sources in the <code>pyproject.toml</code> or via <code>pypi.*</code> configurations.</p> <p>Add sources in <code>pyproject.toml</code>:</p> <pre><code>[[tool.pdm.source]]\nname = \"private\"\nurl = \"https://private.pypi.org/simple\"\nverify_ssl = true\n</code></pre> <p>Change the default index via <code>pdm config</code>:</p> <pre><code>pdm config pypi.url \"https://test.pypi.org/simple\"\n</code></pre> <p>Add extra indexes via <code>pdm config</code>:</p> <pre><code>pdm config pypi.extra.url \"https://extra.pypi.org/simple\"\n</code></pre> <p>The available configuration options are:</p> <ul> <li><code>url</code>: The URL of the index</li> <li><code>verify_ssl</code>: (Optional)Whether to verify SSL certificates, default to true</li> <li><code>username</code>: (Optional)The username for the index</li> <li><code>password</code>: (Optional)The password for the index</li> <li><code>type</code>: (Optional) index or find_links, default to index</li> </ul> About the source types <p>By default, all sources are PEP 503 style \"indexes\" like pip's <code>--index-url</code> and <code>--extra-index-url</code>, however, you can set the type to <code>find_links</code> which contains files or links to be looked for directly. See this answer for the difference between the two types.</p> <p>These configurations are read in the following order to build the final source list:</p> <ul> <li><code>pypi.url</code>, if <code>pypi</code> doesn't appear in the <code>name</code> field of any source in <code>pyproject.toml</code></li> <li>Sources in <code>pyproject.toml</code></li> <li><code>pypi.&lt;name&gt;.url</code> in PDM config.</li> </ul> <p>You can set <code>pypi.ignore_stored_index</code> to <code>true</code> to disable all indexes from the PDM config and only use those specified in <code>pyproject.toml</code>.</p> <p>Disable the default PyPI index</p> <p>If you want to omit the default PyPI index, just set the source name to <code>pypi</code> and that source will replace it.</p> <pre><code>[[tool.pdm.source]]\nurl = \"https://private.pypi.org/simple\"\nverify_ssl = true\nname = \"pypi\"\n</code></pre> Indexes in <code>pyproject.toml</code> or config <p>When you want to share the indexes with other people who are going to use the project, you should add them in <code>pyproject.toml</code>. For example, some packages only exist in a private index and can't be installed if someone doesn't configure the index. Otherwise, store them in the local config which won't be seen by others.</p>"},{"location":"usage/config/#respect-the-order-of-the-sources","title":"Respect the order of the sources","text":"<p>By default, all sources are considered equal, packages from them are sorted by the version and wheel tags, the most matching one with the highest version is selected.</p> <p>In some cases you may want to return packages from the preferred source, and search for others if they are missing from the former source. PDM supports this by reading the configuration <code>respect-source-order</code>:</p> <pre><code>[tool.pdm.resolution]\nrespect-source-order = true\n</code></pre>"},{"location":"usage/config/#specify-index-for-individual-packages","title":"Specify index for individual packages","text":"<p>You can bind packages to specific sources with <code>include_packages</code> and <code>exclude_packages</code> config under <code>tool.pdm.source</code> table.</p> <pre><code>[[tool.pdm.source]]\nname = \"private\"\nurl = \"https://private.pypi.org/simple\"\ninclude_packages = [\"foo\", \"foo-*\"]\nexclude_packages = [\"bar-*\"]\n</code></pre> <p>With the above configuration, any package matching <code>foo</code> or <code>foo-*</code> will only be searched from the <code>private</code> index, and any package matching <code>bar-*</code> will be searched from all indexes except <code>private</code>.</p> <p>Both <code>include_packages</code> and <code>exclude_packages</code> are optional and accept a list of glob patterns, and <code>include_packages</code> takes effect exclusively when the pattern matches.</p>"},{"location":"usage/config/#store-credentials-with-the-index","title":"Store credentials with the index","text":"<p>You can specify credentials in the URL with <code>${ENV_VAR}</code> variable expansion and these variables will be read from the environment variables:</p> <pre><code>[[tool.pdm.source]]\nname = \"private\"\nurl = \"https://${PRIVATE_PYPI_USERNAME}:${PRIVATE_PYPI_PASSWORD}@private.pypi.org/simple\"\n</code></pre>"},{"location":"usage/config/#configure-https-certificates","title":"Configure HTTPS certificates","text":"<p>You can use a custom CA bundle or client certificate for HTTPS requests. It can be configured for both indexes(for package download) and repositories(for upload):</p> <pre><code>pdm config pypi.ca_certs /path/to/ca_bundle.pem\npdm config repository.pypi.ca_certs /path/to/ca_bundle.pem\n</code></pre> <p>Besides, it is possible to use the system trust store, instead of the bundled certifi certificates for verifying HTTPS certificates. This approach will typically support corporate proxy certificates without additional configuration.</p> <p>To use <code>truststore</code>, you need Python 3.10 or newer and install <code>truststore</code> into the same environment as PDM:</p> <pre><code>$ pdm self add truststore\n</code></pre>"},{"location":"usage/config/#index-configuration-merging","title":"Index configuration merging","text":"<p>Index configurations are merged with the <code>name</code> field of <code>[[tool.pdm.source]]</code> table or <code>pypi.&lt;name&gt;</code> key in the config file. This enables you to store the url and credentials separately, to avoid secrets being exposed in the source control. For example, if you have the following configuration:</p> <pre><code>[[tool.pdm.source]]\nname = \"private\"\nurl = \"https://private.pypi.org/simple\"\n</code></pre> <p>You can store the credentials in the config file:</p> <pre><code>pdm config pypi.private.username \"foo\"\npdm config pypi.private.password \"bar\"\n</code></pre> <p>PDM can retrieve the configurations for <code>private</code> index from both places.</p> <p>If the index requires a username and password, but they can't be found from the environment variables nor config file, PDM will prompt you to enter them. Or, if <code>keyring</code> is installed, it will be used as the credential store. PDM can use the <code>keyring</code> from either the installed package or the CLI.</p>"},{"location":"usage/config/#central-installation-caches","title":"Central installation caches","text":"<p>If a package is required by many projects on the system, each project has to keep its own copy. This can be a waste of disk space, especially for data science and machine learning projects.</p> <p>PDM supports caching installations of the same wheel by installing it in a centralized package repository and linking to that installation in different projects. To enable it, run:</p> <pre><code>pdm config install.cache on\n</code></pre> <p>It can be enabled on a per-project basis by adding the <code>--local</code> option to the command.</p> <p>The caches are located in <code>$(pdm config cache_dir)/packages</code>. You can view the cache usage with <code>pdm cache info</code>. Note that the cached installs are managed automatically -- they will be deleted if they are not linked to any projects. Manually deleting the caches from disk may break some projects on the system.</p> <p>In addition, several different ways of linking to cache entries are supported:</p> <ul> <li><code>symlink</code>(default), create symlinks to the package files.</li> <li><code>hardlink</code>, create hard links to the package files of the cache entry.</li> </ul> <p>You can switch between them by running <code>pdm config [-l] install.cache_method &lt;method&gt;</code>.</p> <p>Note</p> <p>Only the installation of named requirements resolved from PyPI can be cached.</p>"},{"location":"usage/config/#configure-the-repositories-for-upload","title":"Configure the repositories for upload","text":"<p>When using the <code>pdm publish</code> command, it reads the repository secrets from the global config file(<code>&lt;CONFIG_ROOT&gt;/config.toml</code>). The content of the config is as follows:</p> <pre><code>[repository.pypi]\nusername = \"frostming\"\npassword = \"&lt;secret&gt;\"\n\n[repository.company]\nurl = \"https://pypi.company.org/legacy/\"\nusername = \"frostming\"\npassword = \"&lt;secret&gt;\"\nca_certs = \"/path/to/custom-cacerts.pem\"\n</code></pre> <p>Alternatively, these credentials can be provided with env vars:</p> <pre><code>export PDM_PUBLISH_REPO=...\nexport PDM_PUBLISH_USERNAME=...\nexport PDM_PUBLISH_PASSWORD=...\nexport PDM_PUBLISH_CA_CERTS=...\n</code></pre> <p>A PEM-encoded Certificate Authority bundle (<code>ca_certs</code>) can be used for local / custom PyPI repositories where the server certificate is not signed by the standard certifi CA bundle.</p> <p>Note</p> <p>Repositories are different from indexes in the previous section. Repositories are for publishing while indexes are for locking and resolving. They don't share the configuration.</p> <p>Tip</p> <p>You don't need to configure the <code>url</code> for <code>pypi</code> and <code>testpypi</code> repositories, they are filled by default values. The username, password, and certificate authority bundle can be passed in from the command line for <code>pdm publish</code> via <code>--username</code>, <code>--password</code>, and <code>--ca-certs</code>, respectively.</p> <p>To change the repository config from the command line, use the <code>pdm config</code> command:</p> <pre><code>pdm config repository.pypi.username \"__token__\"\npdm config repository.pypi.password \"my-pypi-token\"\n\npdm config repository.company.url \"https://pypi.company.org/legacy/\"\npdm config repository.company.ca_certs \"/path/to/custom-cacerts.pem\"\n</code></pre>"},{"location":"usage/config/#password-management-with-keyring","title":"Password management with keyring","text":"<p>When keyring is available and supported, the passwords will be stored to and retrieved from the keyring instead of writing to the config file. This supports both indexes and upload repositories. The service name will be <code>pdm-pypi-&lt;name&gt;</code> for an index and <code>pdm-repository-&lt;name&gt;</code> for a repository.</p> <p>You can enable keyring by either installing <code>keyring</code> into the same environment as PDM or installing globally. To add keyring to the PDM environment:</p> <pre><code>pdm self add keyring\n</code></pre> <p>Alternatively, if you have installed a copy of keyring globally, make sure the CLI is exposed in the <code>PATH</code> env var to make it discoverable by PDM:</p> <pre><code>export PATH=$PATH:path/to/keyring/bin\n</code></pre>"},{"location":"usage/config/#override-the-resolved-package-versions","title":"Override the resolved package versions","text":"<p>Added in version 1.12.0</p> <p>Sometimes you can't get a dependency resolution due to incorrect version ranges set by upstream libraries that you can't fix. In this case you can use PDM's overrides feature to force a specific version of a package to be installed.</p> <p>Given the following configuration in <code>pyproject.toml</code>:</p> <pre><code>[tool.pdm.resolution.overrides]\nasgiref = \"3.2.10\"  # exact version\nurllib3 = \"&gt;=1.26.2\"  # version range\npytz = \"https://mypypi.org/packages/pytz-2020.9-py3-none-any.whl\"  # absolute URL\n</code></pre> <p>Each entry of that table is a package name with the wanted version. In this example, PDM will resolve the above packages into the given versions no matter whether there is any other resolution available.</p> <p>Warning</p> <p>By using <code>[tool.pdm.resolution.overrides]</code> setting, you are at your own risk of any incompatibilities from that resolution. It can only be used if there is no valid resolution for your requirements and you know the specific version works. Most of the time, you can just add any transient constraints to the <code>dependencies</code> array.</p>"},{"location":"usage/config/#exclude-specific-packages-and-their-dependencies-from-the-lock-file","title":"Exclude specific packages and their dependencies from the lock file","text":"<p>Added in version 2.12.0</p> <p>Sometimes you don't even want to include certain packages in the locked file because you are sure they won't be used by any code. In this case, you can completely skip them and their dependencies during dependency resolution:</p> <pre><code>[tool.pdm.resolution]\nexcludes = [\"requests\"]\n</code></pre> <p>With this config, <code>requests</code> will not be locked in the lockfile, and its dependencies such as <code>urllib3</code> and <code>idna</code> will also not show up in the resolution result, if not depended on by other packages. The installer will not be able to pick them up either.</p>"},{"location":"usage/config/#passing-constant-arguments-to-every-pdm-invocation","title":"Passing constant arguments to every pdm invocation","text":"<p>Added in version 2.7.0</p> <p>You can add extra options passed to individual pdm commands by <code>tool.pdm.options</code> configuration:</p> <pre><code>[tool.pdm.options]\nadd = [\"--no-isolation\", \"--no-self\"]\ninstall = [\"--no-self\"]\nlock = [\"--no-cross-platform\"]\n</code></pre> <p>These options will be added right after the command name. For instance, based on the configuration above, <code>pdm add requests</code> is equivalent to <code>pdm add --no-isolation --no-self requests</code>.</p>"},{"location":"usage/config/#ignore-package-warnings","title":"Ignore package warnings","text":"<p>Added in version 2.10.0</p> <p>You may see some warnings when resolving dependencies like this:</p> <pre><code>PackageWarning: Skipping scipy@1.10.0 because it requires Python\n&lt;3.12,&gt;=3.8 but the project claims to work with Python&gt;=3.9.\nNarrow down the `requires-python` range to include this version. For example, \"&gt;=3.9,&lt;3.12\" should work.\n  warnings.warn(record.message, PackageWarning, stacklevel=1)\nUse `-q/--quiet` to suppress these warnings, or ignore them per-package with `ignore_package_warnings` config in [tool.pdm] table.\n</code></pre> <p>This is because the supported range of Python versions of the package doesn't cover the <code>requires-python</code> value specified in the <code>pyproject.toml</code>. You can ignore these warnings in a per-package basis by adding the following config:</p> <pre><code>[tool.pdm]\nignore_package_warnings = [\"scipy\", \"tensorflow-*\"]\n</code></pre> <p>Where each item is a case-insensitive glob pattern to match the package name.</p>"},{"location":"usage/dependency/","title":"Manage Dependencies","text":"<p>PDM provides a bunch of handful commands to help manage your project and dependencies. The following examples are run on Ubuntu 18.04, a few changes must be done if you are using Windows.</p>"},{"location":"usage/dependency/#add-dependencies","title":"Add dependencies","text":"<p><code>pdm add</code> can be followed by one or several dependencies, and the dependency specification is described in PEP 508.</p> <p>Examples:</p> <pre><code>pdm add requests   # add requests\npdm add requests==2.25.1   # add requests with version constraint\npdm add requests[socks]   # add requests with extra dependency\npdm add \"flask&gt;=1.0\" flask-sqlalchemy   # add multiple dependencies with different specifiers\n</code></pre> <p>PDM also allows extra dependency groups by providing <code>-G/--group &lt;name&gt;</code> option, and those dependencies will go to <code>[project.optional-dependencies.&lt;name&gt;]</code> table in the project file, respectively.</p> <p>You can reference other optional groups in <code>optional-dependencies</code>, even before the package is uploaded:</p> <pre><code>[project]\nname = \"foo\"\nversion = \"0.1.0\"\n\n[project.optional-dependencies]\nsocks = [\"pysocks\"]\njwt = [\"pyjwt\"]\nall = [\"foo[socks,jwt]\"]\n</code></pre> <p>After that, dependencies and sub-dependencies will be resolved properly and installed for you, you can view <code>pdm.lock</code> to see the resolved result of all dependencies.</p>"},{"location":"usage/dependency/#local-dependencies","title":"Local dependencies","text":"<p>Local packages can be added with their paths. The path can be a file or a directory:</p> <pre><code>pdm add ./sub-package\npdm add ./first-1.0.0-py2.py3-none-any.whl\n</code></pre> <p>The paths MUST start with a <code>.</code>, otherwise it will be recognized as a normal named requirement. The local dependencies will be written to the <code>pyproject.toml</code> file with the URL format:</p> <pre><code>[project]\ndependencies = [\n\"sub-package @ file:///${PROJECT_ROOT}/sub-package\",\n\"first @ file:///${PROJECT_ROOT}/first-1.0.0-py2.py3-none-any.whl\",\n]\n</code></pre> Using other build backends <p>If you are using <code>hatchling</code> instead of the pdm backend, the URLs would be as follows:</p> <p><pre><code>sub-package @ {root:uri}/sub-package\nfirst @ {root:uri}/first-1.0.0-py2.py3-none-any.whl\n</code></pre> Other backends doesn't support encoding relative paths in the URL and will write the absolute path instead.</p>"},{"location":"usage/dependency/#url-dependencies","title":"URL dependencies","text":"<p>PDM also supports downloading and installing packages directly from a web address.</p> <p>Examples:</p> <pre><code># Install gzipped package from a plain URL\npdm add \"https://github.com/numpy/numpy/releases/download/v1.20.0/numpy-1.20.0.tar.gz\"\n# Install wheel from a plain URL\npdm add \"https://github.com/explosion/spacy-models/releases/download/en_core_web_trf-3.5.0/en_core_web_trf-3.5.0-py3-none-any.whl\"\n</code></pre>"},{"location":"usage/dependency/#vcs-dependencies","title":"VCS dependencies","text":"<p>You can also install from a git repository url or other version control systems. The following are supported:</p> <ul> <li>Git: <code>git</code></li> <li>Mercurial: <code>hg</code></li> <li>Subversion: <code>svn</code></li> <li>Bazaar: <code>bzr</code></li> </ul> <p>The URL should be like: <code>{vcs}+{url}@{rev}</code></p> <p>Examples:</p> <pre><code># Install pip repo on tag `22.0`\npdm add \"git+https://github.com/pypa/pip.git@22.0\"\n# Provide credentials in the URL\npdm add \"git+https://username:password@github.com/username/private-repo.git@master\"\n# Give a name to the dependency\npdm add \"pip @ git+https://github.com/pypa/pip.git@22.0\"\n# Or use the #egg fragment\npdm add \"git+https://github.com/pypa/pip.git@22.0#egg=pip\"\n# Install from a subdirectory\npdm add \"git+https://github.com/owner/repo.git@master#egg=pkg&amp;subdirectory=subpackage\"\n</code></pre>"},{"location":"usage/dependency/#hide-credentials-in-the-url","title":"Hide credentials in the URL","text":"<p>You can hide the credentials in the URL by using the <code>${ENV_VAR}</code> variable syntax:</p> <pre><code>[project]\ndependencies = [\n\"mypackage @ git+http://${VCS_USER}:${VCS_PASSWD}@test.git.com/test/mypackage.git@master\"\n]\n</code></pre> <p>These variables will be read from the environment variables when installing the project.</p>"},{"location":"usage/dependency/#add-development-only-dependencies","title":"Add development only dependencies","text":"<p>Added in version 1.5.0</p> <p>PDM also supports defining groups of dependencies that are useful for development, e.g. some for testing and others for linting. We usually don't want these dependencies appear in the distribution's metadata so using <code>optional-dependencies</code> is probably not a good idea. We can define them as development dependencies:</p> <pre><code>pdm add -dG test pytest\n</code></pre> <p>This will result in a pyproject.toml as following:</p> <pre><code>[tool.pdm.dev-dependencies]\ntest = [\"pytest\"]\n</code></pre> <p>You can have several groups of development only dependencies. Unlike <code>optional-dependencies</code>, they won't appear in the package distribution metadata such as <code>PKG-INFO</code> or <code>METADATA</code>. The package index won't be aware of these dependencies. The schema is similar to that of <code>optional-dependencies</code>, except that it is in <code>tool.pdm</code> table.</p> <p><pre><code>[tool.pdm.dev-dependencies]\nlint = [\n\"flake8\",\n\"black\"\n]\ntest = [\"pytest\", \"pytest-cov\"]\ndoc = [\"mkdocs\"]\n</code></pre> For backward-compatibility, if only <code>-d</code> or <code>--dev</code> is specified, dependencies will go to <code>dev</code> group under <code>[tool.pdm.dev-dependencies]</code> by default.</p> <p>Note</p> <p>The same group name MUST NOT appear in both <code>[tool.pdm.dev-dependencies]</code> and <code>[project.optional-dependencies]</code>.</p>"},{"location":"usage/dependency/#editable-dependencies","title":"Editable dependencies","text":"<p>Local directories and VCS dependencies can be installed in editable mode. If you are familiar with <code>pip</code>, it is just like <code>pip install -e &lt;package&gt;</code>. Editable packages are allowed only in development dependencies:</p> <p>Note</p> <p>Editable installs are only allowed in the <code>dev</code> dependency group. Other groups, including the default, will fail with a <code>[PdmUsageError]</code>.</p> <pre><code># A relative path to the directory\npdm add -e ./sub-package --dev\n# A file URL to a local directory\npdm add -e file:///path/to/sub-package --dev\n# A VCS URL\npdm add -e git+https://github.com/pallets/click.git@main#egg=click --dev\n</code></pre>"},{"location":"usage/dependency/#save-version-specifiers","title":"Save version specifiers","text":"<p>If the package is given without a version specifier like <code>pdm add requests</code>. PDM provides three different behaviors of what version specifier is saved for the dependency, which is given by <code>--save-&lt;strategy&gt;</code>(Assume <code>2.21.0</code> is the latest version that can be found for the dependency):</p> <ul> <li><code>minimum</code>: Save the minimum version specifier: <code>&gt;=2.21.0</code> (default).</li> <li><code>compatible</code>: Save the compatible version specifier: <code>&gt;=2.21.0,&lt;3.0.0</code>.</li> <li><code>exact</code>: Save the exact version specifier: <code>==2.21.0</code>.</li> <li><code>wildcard</code>: Don't constrain version and leave the specifier to be wildcard: <code>*</code>.</li> </ul>"},{"location":"usage/dependency/#add-prereleases","title":"Add prereleases","text":"<p>One can give <code>--pre/--prerelease</code> option to <code>pdm add</code> so that prereleases are allowed to be pinned for the given packages.</p>"},{"location":"usage/dependency/#update-existing-dependencies","title":"Update existing dependencies","text":"<p>To update all dependencies in the lock file:</p> <pre><code>pdm update\n</code></pre> <p>To update the specified package(s):</p> <pre><code>pdm update requests\n</code></pre> <p>To update multiple groups of dependencies:</p> <pre><code>pdm update -G security -G http\n</code></pre> <p>Or using comma-separated list:</p> <pre><code>pdm update -G \"security,http\"\n</code></pre> <p>To update a given package in the specified group:</p> <pre><code>pdm update -G security cryptography\n</code></pre> <p>If the group is not given, PDM will search for the requirement in the default dependencies set and raises an error if none is found.</p> <p>To update packages in development dependencies:</p> <pre><code># Update all default + dev-dependencies\npdm update -d\n# Update a package in the specified group of dev-dependencies\npdm update -dG test pytest\n</code></pre>"},{"location":"usage/dependency/#about-update-strategy","title":"About update strategy","text":"<p>Similarly, PDM also provides 3 different behaviors of updating dependencies and sub-dependencies\uff0c which is given by <code>--update-&lt;strategy&gt;</code> option:</p> <ul> <li><code>reuse</code>: Keep all locked dependencies except for those given in the command line (default).</li> <li><code>reuse-installed</code>: Try to reuse the versions installed in the working set. This will also affect the packages requested in the command line.</li> <li><code>eager</code>: Try to lock a newer version of the packages in command line and their recursive sub-dependencies and keep other dependencies as they are.</li> <li><code>all</code>: Update all dependencies and sub-dependencies.</li> </ul>"},{"location":"usage/dependency/#update-packages-to-the-versions-that-break-the-version-specifiers","title":"Update packages to the versions that break the version specifiers","text":"<p>One can give <code>-u/--unconstrained</code> to tell PDM to ignore the version specifiers in the <code>pyproject.toml</code>. This works similarly to the <code>yarn upgrade -L/--latest</code> command. Besides, <code>pdm update</code> also supports the <code>--pre/--prerelease</code> option.</p>"},{"location":"usage/dependency/#remove-existing-dependencies","title":"Remove existing dependencies","text":"<p>To remove existing dependencies from project file and the library directory:</p> <pre><code># Remove requests from the default dependencies\npdm remove requests\n# Remove h11 from the 'web' group of optional-dependencies\npdm remove -G web h11\n# Remove pytest-cov from the `test` group of dev-dependencies\npdm remove -dG test pytest-cov\n</code></pre>"},{"location":"usage/dependency/#install-the-packages-pinned-in-lock-file","title":"Install the packages pinned in lock file","text":"<p>There are a few similar commands to do this job with slight differences:</p> <ul> <li><code>pdm sync</code> installs packages from the lock file.</li> <li><code>pdm update</code> will update the lock file, then <code>sync</code>.</li> <li><code>pdm install</code> will check the project file for changes, update the lock file if needed, then <code>sync</code>.</li> </ul> <p><code>sync</code> also has a few options to manage installed packages:</p> <ul> <li><code>--clean</code>: will remove packages no longer in the lockfile</li> <li><code>--only-keep</code>: only selected packages (using options like <code>-G</code> or <code>--prod</code>) will be kept.</li> </ul>"},{"location":"usage/dependency/#specify-the-lockfile-to-use","title":"Specify the lockfile to use","text":"<p>You can specify another lockfile than the default <code>pdm lock</code> by using the <code>-L/--lockfile &lt;filepath&gt;</code> option or the <code>PDM_LOCKFILE</code> environment variable.</p>"},{"location":"usage/dependency/#select-a-subset-of-dependency-groups-to-be-installed-or-locked","title":"Select a subset of dependency groups to be installed or locked","text":"<p>Say we have a project with following dependencies:</p> <pre><code>[project]  # This is production dependencies\ndependencies = [\"requests\"]\n\n[project.optional-dependencies]  # This is optional dependencies\nextra1 = [\"flask\"]\nextra2 = [\"django\"]\n\n[tool.pdm.dev-dependencies]  # This is dev dependencies\ndev1 = [\"pytest\"]\ndev2 = [\"mkdocs\"]\n</code></pre> Command What it does Comments <code>pdm install</code> install all groups locked in the lockfile <code>pdm install -G extra1</code> install prod deps, dev deps, and \"extra1\" optional group <code>pdm install -G dev1</code> install prod deps and only \"dev1\" dev group <code>pdm install -G:all</code> install prod deps, dev deps and \"extra1\", \"extra2\" optional groups <code>pdm install -G extra1 -G dev1</code> install prod deps, \"extra1\" optional group and only \"dev1\" dev group <code>pdm install --prod</code> install prod only <code>pdm install --prod -G extra1</code> install prod deps and \"extra1\" optional <code>pdm install --prod -G dev1</code> Fail, <code>--prod</code> can't be given with dev dependencies Leave the <code>--prod</code> option <p>All development dependencies are included as long as <code>--prod</code> is not passed and <code>-G</code> doesn't specify any dev groups.</p> <p>Besides, if you don't want the root project to be installed, add <code>--no-self</code> option, and <code>--no-editable</code> can be used when you want all packages to be installed in non-editable versions.</p> <p>You may also use the pdm lock command with these options to lock only the specified groups, which will be recorded in the <code>[metadata]</code> table of the lock file. If no <code>--group/--prod/--dev/--no-default</code> option is specified, <code>pdm sync</code> and <code>pdm update</code> will operate using the groups in the lockfile. However, if any groups that are not included in the lockfile are given as arguments to the commands, PDM will raise an error.</p> <p>This feature is especially valuable when managing multiple lockfiles, where each may have different versions of the same package pinned. To switch between lockfiles, you can use the <code>--lockfile/-L</code> option.</p> <p>For a realistic example, your project depends on a release version of <code>werkzeug</code> and you may want to work with a local in-development copy of it when developing. You can add the following to your <code>pyproject.toml</code>:</p> <pre><code>[project]\nrequires-python = \"&gt;=3.7\"\ndependencies = [\"werkzeug\"]\n\n[tool.pdm.dev-dependencies]\ndev = [\"werkzeug @ file:///${PROJECT_ROOT}/dev/werkzeug\"]\n</code></pre> <p>Then, run <code>pdm lock</code> with different options to generate lockfiles for different purposes:</p> <pre><code># Lock default + dev, write to pdm.lock\n# with the local copy of werkzeug pinned.\npdm lock\n# Lock default, write to pdm.prod.lock\n# with the release version of werkzeug pinned.\npdm lock --prod -L pdm.prod.lock\n</code></pre> <p>Check the <code>metadata.groups</code> field in the lockfile to see which groups are included.</p>"},{"location":"usage/dependency/#lock-strategies","title":"Lock strategies","text":"<p>Currently, we support three flags to control the locking behavior: <code>cross_platform</code>, <code>static_urls</code> and <code>direct_minimal_versions</code>, with the meanings as follows. You can pass one or more flags to <code>pdm lock</code> by <code>--strategy/-S</code> option, either by giving a comma-separated list or by passing the option multiple times. Both of these commands function in the same way:</p> <pre><code>pdm lock -S cross_platform,static_urls\npdm lock -S cross_platform -S static_urls\n</code></pre> <p>The flags will be encoded in the lockfile and get read when you run <code>pdm lock</code> next time. But you can disable flags by prefixing the flag name with <code>no_</code>:</p> <pre><code>pdm lock -S no_cross_platform\n</code></pre> <p>This command makes the lockfile not cross-platform.</p>"},{"location":"usage/dependency/#cross-platform","title":"Cross platform","text":"<p>Added in version 2.6.0</p> <p>By default, the generated lockfile is cross-platform, which means the current platform isn't taken into account when resolving the dependencies. The result lockfile will contain wheels and dependencies for all possible platforms and Python versions. However, sometimes this will result in a wrong lockfile when a release doesn't contain all wheels. To avoid this, you can tell PDM to create a lockfile that works for this platform only, trimming the wheels not relevant to the current platform. This can be done by passing the <code>--strategy no_cross_platform</code> option to <code>pdm lock</code>:</p> <pre><code>pdm lock --strategy no_cross_platform\n</code></pre>"},{"location":"usage/dependency/#static-urls","title":"Static URLs","text":"<p>Added in version 2.8.0</p> <p>By default, PDM only stores the filenames of the packages in the lockfile, which benefits the reusability across different package indexes. However, if you want to store the static URLs of the packages in the lockfile, you can pass the <code>--strategy static_urls</code> option to <code>pdm lock</code>:</p> <pre><code>pdm lock --strategy static_urls\n</code></pre> <p>The settings will be saved and remembered for the same lockfile. You can also pass <code>--strategy no_static_urls</code> to disable it.</p>"},{"location":"usage/dependency/#direct-minimal-versions","title":"Direct minimal versions","text":"<p>Added in version 2.10.0</p> <p>When it is enabled by passing <code>--strategy direct_minimal_versions</code>, dependencies specified in the <code>pyproject.toml</code> will be resolved to the minimal versions available, rather than the latest versions. This is useful when you want to test the compatibility of your project within a range of dependency versions.</p> <p>For example, if you specified <code>flask&gt;=2.0</code> in the <code>pyproject.toml</code>, <code>flask</code> will be resolved to version <code>2.0.0</code> if there is no other compatibility issue.</p> <p>Note</p> <p>Version constraints in package dependencies are not future-proof. If you resolve the dependencies to the minimal versions, there will likely be backwards-compatibility issues. For example, <code>flask==2.0.0</code> requires <code>werkzeug&gt;=2.0</code>, but in fact, it can not work with <code>Werkzeug 3.0.0</code>, which is released 2 years after it.</p>"},{"location":"usage/dependency/#inherit-the-metadata-from-parents","title":"Inherit the metadata from parents","text":"<p>Added in version 2.11.0</p> <p>Previously, the <code>pdm lock</code> command would record package metadata as it is. When installing, PDM would start from the top requirements and traverse down to the leaf node of the dependency tree. It would then evaluate any marker it encounters against the current environment. If a marker is not satisfied, the package would be discarded. In other words, we need an additional \"resolution\" step in installation.</p> <p>When the <code>inherit_metadata</code> strategy is enabled, PDM will inherit and merge environment markers from a package's ancestors. These markers are then encoded in the lockfile during locking, resulting in faster installations. This has been enabled by default from version <code>2.11.0</code>, to disable this strategy in the config, use <code>pdm config strategy.inherit_metadata false</code>.</p>"},{"location":"usage/dependency/#show-what-packages-are-installed","title":"Show what packages are installed","text":"<p>Similar to <code>pip list</code>, you can list all packages installed in the packages directory:</p> <pre><code>pdm list\n</code></pre>"},{"location":"usage/dependency/#include-and-exclude-groups","title":"Include and exclude groups","text":"<p>By default, all packages installed in the working set will be listed. You can specify which groups to be listed by <code>--include/--exclude</code> options, and <code>include</code> has a higher priority than <code>exclude</code>.</p> <pre><code>pdm list --include dev\npdm list --exclude test\n</code></pre> <p>There is a special group <code>:sub</code>, when included, all transitive dependencies will also be shown. It is included by default.</p> <p>You can also pass <code>--resolve</code> to <code>pdm list</code>, which will show the packages resolved in <code>pdm.lock</code>, rather than installed in the working set.</p>"},{"location":"usage/dependency/#change-the-output-fields-and-format","title":"Change the output fields and format","text":"<p>By default, name, version and location will be shown in the list output, you can view more fields or specify the order of fields by <code>--fields</code> option:</p> <pre><code>pdm list --fields name,licenses,version\n</code></pre> <p>For all supported fields, please refer to the CLI reference.</p> <p>Also, you can specify the output format other than the default table output. The supported formats and options are <code>--csv</code>, <code>--json</code>, <code>--markdown</code> and <code>--freeze</code>.</p>"},{"location":"usage/dependency/#show-the-dependency-tree","title":"Show the dependency tree","text":"<p>Or show a dependency tree by:</p> <pre><code>$ pdm list --tree\ntempenv 0.0.0\n\u2514\u2500\u2500 click 7.0 [ required: &lt;7.0.0,&gt;=6.7 ]\nblack 19.10b0\n\u251c\u2500\u2500 appdirs 1.4.3 [ required: Any ]\n\u251c\u2500\u2500 attrs 19.3.0 [ required: &gt;=18.1.0 ]\n\u251c\u2500\u2500 click 7.0 [ required: &gt;=6.5 ]\n\u251c\u2500\u2500 pathspec 0.7.0 [ required: &lt;1,&gt;=0.6 ]\n\u251c\u2500\u2500 regex 2020.2.20 [ required: Any ]\n\u251c\u2500\u2500 toml 0.10.0 [ required: &gt;=0.9.4 ]\n\u2514\u2500\u2500 typed-ast 1.4.1 [ required: &gt;=1.4.0 ]\nbump2version 1.0.0\n</code></pre> <p>Note that <code>--fields</code> option doesn't work with <code>--tree</code>.</p>"},{"location":"usage/dependency/#filter-packages-by-patterns","title":"Filter packages by patterns","text":"<p>You can also limit the packages to show by passing the patterns to <code>pdm list</code>:</p> <pre><code>pdm list flask-* requests-*\n</code></pre> Be careful with the shell expansion <p>In most shells, the wildcard <code>*</code> will be expanded if there are matching files under the current directory. To avoid getting unexpected results, you can wrap the patterns with single quotes: <code>pdm list 'flask-*' 'requests-*'</code>.</p> <p>In <code>--tree</code> mode, only the subtree of the matched packages will be displayed. This can be used to achieve the same purpose as <code>pnpm why</code>, which is to show why a specific package is required.</p> <pre><code>$ pdm list --tree --reverse certifi\ncertifi 2023.7.22\n\u2514\u2500\u2500 requests 2.31.0 [ requires: &gt;=2017.4.17 ]\n\u2514\u2500\u2500 cachecontrol[filecache] 0.13.1 [ requires: &gt;=2.16.0 ]\n</code></pre>"},{"location":"usage/dependency/#allow-prerelease-versions-to-be-installed","title":"Allow prerelease versions to be installed","text":"<p>Include the following setting in <code>pyproject.toml</code> to enable:</p> <pre><code>[tool.pdm.resolution]\nallow-prereleases = true\n</code></pre>"},{"location":"usage/dependency/#set-acceptable-format-for-locking-or-installing","title":"Set acceptable format for locking or installing","text":"<p>If you want to control the format(binary/sdist) of the packages, you can set the env vars <code>PDM_NO_BINARY</code> and <code>PDM_ONLY_BINARY</code>.</p> <p>Each env var is a comma-separated list of package name. You can set it to <code>:all:</code> to apply to all packages. For example:</p> <pre><code># No binary for werkzeug will be locked nor used for installation\nPDM_NO_BINARY=werkzeug pdm add flask\n# Only binaries will be locked in the lock file\nPDM_ONLY_BINARY=:all: pdm lock\n# No binaries will be used for installation\nPDM_NO_BINARY=:all: pdm install\n# Prefer binary distributions and even if sdist with higher version is available\nPDM_PREFER_BINARY=flask pdm install\n</code></pre>"},{"location":"usage/dependency/#solve-the-locking-failure","title":"Solve the locking failure","text":"<p>If PDM is not able to find a resolution to satisfy the requirements, it will raise an error. For example,</p> <pre><code>pdm django==3.1.4 \"asgiref&lt;3\"\n...\n\ud83d\udd12 Lock failed\nUnable to find a resolution for asgiref because of the following conflicts:\n  asgiref&lt;3 (from project)\nasgiref&lt;4,&gt;=3.2.10 (from &lt;Candidate django 3.1.4 from https://pypi.org/simple/django/&gt;)\nTo fix this, you could loosen the dependency version constraints in pyproject.toml. If that is not possible, you could also override the resolved version in `[tool.pdm.resolution.overrides]` table.\n</code></pre> <p>You can either change to a lower version of <code>django</code> or remove the upper bound of <code>asgiref</code>. But if it is not eligible for your project, you can try overriding the resolved package versions or even don't lock that specific package in <code>pyproject.toml</code>.</p>"},{"location":"usage/dependency/#manage-global-project","title":"Manage global project","text":"<p>Sometimes users may want to keep track of the dependencies of global Python interpreter as well. It is easy to do so with PDM, via <code>-g/--global</code> option which is supported by most subcommands.</p> <p>If the option is passed, <code>&lt;CONFIG_ROOT&gt;/global-project</code> will be used as the project directory, which is almost the same as normal project except that <code>pyproject.toml</code> will be created automatically for you and it doesn't support build features. The idea is taken from Haskell's stack.</p> <p>However, unlike <code>stack</code>, by default, PDM won't use global project automatically if a local project is not found. Users should pass <code>-g/--global</code> explicitly to activate it, since it is not very pleasing if packages go to a wrong place. But PDM also leave the decision to users, just set the config <code>global_project.fallback</code> to <code>true</code>.</p> <p>By default, when <code>pdm</code> uses global project implicitly the following message is printed: <code>Project is not found, fallback to the global project</code>. To disable this message set the config <code>global_project.fallback_verbose</code> to <code>false</code>.</p> <p>If you want global project to track another project file other than <code>&lt;CONFIG_ROOT&gt;/global-project</code>, you can provide the project path via <code>-p/--project &lt;path&gt;</code> option. Especially if you pass <code>--global --project .</code>, PDM will install the dependencies of the current project into the global Python.</p> <p>Warning</p> <p>Be careful with <code>remove</code> and <code>sync --clean/--pure</code> commands when global project is used, because it may remove packages installed in your system Python.</p>"},{"location":"usage/dependency/#export-locked-packages-to-alternative-formats","title":"Export locked packages to alternative formats","text":"<p>You can also export <code>pdm lock</code> to other formats, to ease the CI flow or image building process. Currently, only <code>requirements.txt</code> format is supported:</p> <pre><code>pdm export -o requirements.txt\n</code></pre> <p>Note</p> <p>You can also run <code>pdm export</code> with a <code>.pre-commit</code> hook.</p>"},{"location":"usage/hooks/","title":"Lifecycle and Hooks","text":"<p>As any Python deliverable, your project will go through the different phases of a Python project lifecycle and PDM provides commands to perform the expected tasks for those phases.</p> <p>It also provides hooks attached to these steps allowing for:</p> <ul> <li>plugins to listen to the signals of the same name.</li> <li>developers to define custom scripts with the same name.</li> </ul> <p>Besides, <code>pre_invoke</code> signal is emitted before ANY command is invoked, allowing plugins to modify the project or options beforehand.</p> <p>The built-in commands are currently split into 3 groups:</p> <ul> <li>the initialization phase</li> <li>the dependencies management.</li> <li>the publication phase.</li> </ul> <p>You will most probably need to perform some recurrent tasks between the installation and publication phases (housekeeping, linting, testing, ...) this is why PDM lets you define your own tasks/phases using user scripts.</p> <p>To provides full flexibility, PDM allows to skip some hooks and tasks on demand.</p>"},{"location":"usage/hooks/#initialization","title":"Initialization","text":"<p>The initialization phase should occur only once in a project lifetime by running the <code>pdm init</code> command to initialize an existing project (prompt to fill the <code>pyproject.toml</code> file).</p> <p>They trigger the following hooks:</p> <ul> <li><code>post_init</code></li> </ul> <pre><code>flowchart LR\n  subgraph pdm-init [pdm init]\n    direction LR\n    post-init{{Emit post_init}}\n    init --&gt; post-init\n  end</code></pre>"},{"location":"usage/hooks/#dependencies-management","title":"Dependencies management","text":"<p>The dependencies management is required for the developer to be able to work and perform the following:</p> <ul> <li><code>lock</code>: compute a lock file from the <code>pyproject.toml</code> requirements.</li> <li><code>sync</code>: synchronize (add/remove/update) PEP582 packages from the lock file and install the current project as editable.</li> <li><code>add</code>: add a dependency</li> <li><code>remove</code>: remove a dependency</li> </ul> <p>All those steps are directly available with the following commands:</p> <ul> <li><code>pdm lock</code>: execute the <code>lock</code> task</li> <li><code>pdm sync</code>: execute the <code>sync</code> task</li> <li><code>pdm install</code>: execute the <code>sync</code> task, preceded from <code>lock</code> if required</li> <li><code>pdm add</code>: add a dependency requirement, re-lock and then sync</li> <li><code>pdm remove</code>: remove a dependency requirement, re-lock and then sync</li> <li><code>pdm update</code>: re-lock dependencies from their latest versions and then sync</li> </ul> <p>They trigger the following hooks:</p> <ul> <li><code>pre_install</code></li> <li><code>post_install</code></li> <li><code>pre_lock</code></li> <li><code>post_lock</code></li> </ul> <pre><code>flowchart LR\n  subgraph pdm-install [pdm install]\n    direction LR\n\n    subgraph pdm-lock [pdm lock]\n      direction TB\n      pre-lock{{Emit pre_lock}}\n      post-lock{{Emit post_lock}}\n      pre-lock --&gt; lock --&gt; post-lock\n    end\n\n    subgraph pdm-sync [pdm sync]\n      direction TB\n      pre-install{{Emit pre_install}}\n      post-install{{Emit post_install}}\n      pre-install --&gt; sync --&gt; post-install\n    end\n\n    pdm-lock --&gt; pdm-sync\n  end</code></pre>"},{"location":"usage/hooks/#switching-python-version","title":"Switching Python version","text":"<p>This is a special case in dependency management: you can switch the current Python version using <code>pdm use</code> and it will emit the <code>post_use</code> signal with the new Python interpreter.</p> <pre><code>flowchart LR\n  subgraph pdm-use [pdm use]\n    direction LR\n    post-use{{Emit post_use}}\n    use --&gt; post-use\n  end</code></pre>"},{"location":"usage/hooks/#publication","title":"Publication","text":"<p>As soon as you are ready to publish your package/library, you will require the publication tasks:</p> <ul> <li><code>build</code>: build/compile assets requiring it and package everything into a Python package (sdist, wheel)</li> <li><code>upload</code>: upload/publish the package to a remote PyPI index</li> </ul> <p>All those steps are available with the following commands:</p> <ul> <li><code>pdm build</code></li> <li><code>pdm publish</code></li> </ul> <p>They trigger the following hooks:</p> <ul> <li><code>pre_publish</code></li> <li><code>post_publish</code></li> <li><code>pre_build</code></li> <li><code>post_build</code></li> </ul> <pre><code>flowchart LR\n  subgraph pdm-publish [pdm publish]\n    direction LR\n    pre-publish{{Emit pre_publish}}\n    post-publish{{Emit post_publish}}\n\n    subgraph pdm-build [pdm build]\n      pre-build{{Emit pre_build}}\n      post-build{{Emit post_build}}\n      pre-build --&gt; build --&gt; post-build\n    end\n\n    %% subgraph pdm-upload [pdm upload]\n    %%   pre-upload{{Emit pre_upload}}\n    %%   post-upload{{Emit post_upload}}\n    %%   pre-upload --&gt; upload --&gt; post-upload\n    %% end\n\n    pre-publish --&gt; pdm-build --&gt; upload --&gt; post-publish\n  end</code></pre> <p>Execution will stop at first failure, hooks included.</p>"},{"location":"usage/hooks/#user-scripts","title":"User scripts","text":"<p>User scripts are detailed in their own section but you should know that:</p> <ul> <li>each user script can define a <code>pre_*</code> and <code>post_*</code> script, including composite scripts.</li> <li>each <code>run</code> execution will trigger the <code>pre_run</code> and <code>post_run</code> hooks</li> <li>each script execution will trigger the <code>pre_script</code> and <code>post_script</code> hooks</li> </ul> <p>Given the following <code>scripts</code> definition:</p> <pre><code>[tool.pdm.scripts]\npre_script = \"\"\npost_script = \"\"\npre_test = \"\"\npost_test = \"\"\ntest = \"\"\npre_composite = \"\"\npost_composite = \"\"\ncomposite = {composite = [\"test\"]}\n</code></pre> <p>a <code>pdm run test</code> will have the following lifecycle:</p> <pre><code>flowchart LR\n  subgraph pdm-run-test [pdm run test]\n    direction LR\n    pre-run{{Emit pre_run}}\n    post-run{{Emit post_run}}\n    subgraph run-test [test task]\n      direction TB\n      pre-script{{Emit pre_script}}\n      post-script{{Emit post_script}}\n      pre-test[Execute pre_test]\n      post-test[Execute post_test]\n      test[Execute test]\n\n      pre-script --&gt; pre-test --&gt; test --&gt; post-test --&gt; post-script\n    end\n\n    pre-run --&gt; run-test --&gt; post-run\n  end</code></pre> <p>while <code>pdm run composite</code> will have the following:</p> <pre><code>flowchart LR\n  subgraph pdm-run-composite [pdm run composite]\n    direction LR\n    pre-run{{Emit pre_run}}\n    post-run{{Emit post_run}}\n\n    subgraph run-composite [composite task]\n      direction TB\n      pre-script-composite{{Emit pre_script}}\n      post-script-composite{{Emit post_script}}\n      pre-composite[Execute pre_composite]\n      post-composite[Execute post_composite]\n\n      subgraph run-test [test task]\n        direction TB\n        pre-script-test{{Emit pre_script}}\n        post-script-test{{Emit post_script}}\n        pre-test[Execute pre_test]\n        post-test[Execute post_test]\n\n        pre-script-test --&gt; pre-test --&gt; test --&gt; post-test --&gt; post-script-test\n      end\n\n      pre-script-composite --&gt; pre-composite --&gt; run-test --&gt; post-composite --&gt; post-script-composite\n    end\n\n     pre-run --&gt; run-composite --&gt; post-run\n  end</code></pre>"},{"location":"usage/hooks/#skipping","title":"Skipping","text":"<p>It is possible to control which task and hook runs for any built-in command as well as custom user scripts using the <code>--skip</code> option.</p> <p>It accepts a comma-separated list of hooks/task names to skip as well as the predefined <code>:all</code>, <code>:pre</code> and <code>:post</code> shortcuts respectively skipping all hooks, all <code>pre_*</code> hooks and all <code>post_*</code> hooks. You can also provide the skip list in <code>PDM_SKIP_HOOKS</code> environment variable but it will be overridden as soon as the <code>--skip</code> parameter is provided.</p> <p>Given the previous script block, running <code>pdm run --skip=:pre,post_test composite</code> will result in the following reduced lifecycle:</p> <pre><code>flowchart LR\n  subgraph pdm-run-composite [pdm run composite]\n    direction LR\n    post-run{{Emit post_run}}\n\n    subgraph run-composite [composite task]\n      direction TB\n      post-script-composite{{Emit post_script}}\n      post-composite[Execute post_composite]\n\n      subgraph run-test [test task]\n        direction TB\n        post-script-test{{Emit post_script}}\n\n        test --&gt; post-script-test\n      end\n\n      run-test --&gt; post-composite --&gt; post-script-composite\n    end\n\n     run-composite --&gt; post-run\n  end</code></pre>"},{"location":"usage/pep582/","title":"Working with PEP 582","text":"<p>PEP 582 has been rejected</p> <p>This is a rejected PEP. However, due to the fact that this feature is the reason for PDM's birth, PDM will retain the support. We recommend using virtual environments instead.</p> <p>With PEP 582, dependencies will be installed into <code>__pypackages__</code> directory under the project root. With PEP 582 enabled globally, you can also use the project interpreter to run scripts directly.</p> <p>When the project interpreter is a normal Python, this mode is enabled.</p> <p>Besides, on a project you work with for the first time on your machine, if it contains an empty <code>__pypackages__</code> directory, PEP 582 is enabled automatically, and virtualenv won't be created.</p>"},{"location":"usage/pep582/#enable-pep-582-globally","title":"Enable PEP 582 globally","text":"<p>To make the Python interpreters aware of PEP 582 packages, one need to add the <code>pdm/pep582/sitecustomize.py</code> to the Python library search path.</p> WindowsMac and Linux <p>One just needs to execute <code>pdm --pep582</code>, then environment variable will be changed automatically. Don't forget to restart the terminal session to take effect.</p> <p>The command to change the environment variables can be printed by <code>pdm --pep582 [&lt;SHELL&gt;]</code>. If <code>&lt;SHELL&gt;</code> isn't given, PDM will pick one based on some guesses. You can run <code>eval \"$(pdm --pep582)\"</code> to execute the command.</p> <p>You may want to write a line in your <code>.bash_profile</code>(or similar profiles) to make it effective when logging in. For example, in bash you can do this:</p> <pre><code>pdm --pep582 &gt;&gt; ~/.bash_profile\n</code></pre> <p>Once again, Don't forget to restart the terminal session to take effect.</p> How is it done? <p>Thanks to the site packages loading on Python startup. It is possible to patch the <code>sys.path</code> by executing the <code>sitecustomize.py</code> shipped with PDM. The interpreter can search the directories for the nearest <code>__pypackage__</code> folder and append it to the <code>sys.path</code> variable.</p>"},{"location":"usage/pep582/#configure-ide-to-support-pep-582","title":"Configure IDE to support PEP 582","text":"<p>Now there are no built-in support or plugins for PEP 582 in most IDEs, you have to configure your tools manually.</p>"},{"location":"usage/pep582/#pycharm","title":"PyCharm","text":"<p>Mark <code>__pypackages__/&lt;major.minor&gt;/lib</code> as Sources Root. Then, select as Python interpreter a Python installation with the same <code>&lt;major.minor&gt;</code> version.</p> <p>Additionally, if you want to use tools from the environment (e.g. <code>pytest</code>), you have to add the <code>__pypackages__/&lt;major.minor&gt;/bin</code> directory to the <code>PATH</code> variable in the corresponding run/debug configuration.</p>"},{"location":"usage/pep582/#vscode","title":"VSCode","text":"<p>Add the following two entries to the top-level dict in <code>.vscode/settings.json</code>:</p> <pre><code>{\n\"python.autoComplete.extraPaths\": [\"__pypackages__/&lt;major.minor&gt;/lib\"],\n\"python.analysis.extraPaths\": [\"__pypackages__/&lt;major.minor&gt;/lib\"]\n}\n</code></pre> <p>This file can be auto-generated with plugin <code>pdm-vscode</code>.</p> <p>Enable PEP582 globally, and make sure VSCode runs using the same user and shell you enabled PEP582 for.</p> Cannot enable PEP582 globally? <p>If for some reason you cannot enable PEP582 globally, you can still configure each \"launch\" in each project: set the <code>PYTHONPATH</code> environment variable in your launch configuration, in <code>.vscode/launch.json</code>. For example, to debug your <code>pytest</code> run:</p> <pre><code>{\n\"version\": \"0.2.0\",\n\"configurations\": [\n{\n\"name\": \"pytest\",\n\"type\": \"python\",\n\"request\": \"launch\",\n\"module\": \"pytest\",\n\"args\": [\"tests\"],\n\"justMyCode\": false,\n\"env\": {\"PYTHONPATH\": \"__pypackages__/&lt;major.minor&gt;/lib\"}\n}\n]\n}\n</code></pre> <p>If your package resides in a <code>src</code> directory, add it to <code>PYTHONPATH</code> as well:</p> <pre><code>\"env\": {\"PYTHONPATH\": \"src:__pypackages__/&lt;major.minor&gt;/lib\"}\n</code></pre> Using Pylance/Pyright? <p>If you have configured <code>\"python.analysis.diagnosticMode\": \"workspace\"</code>, and you see a ton of errors/warnings as a result. you may need to create <code>pyrightconfig.json</code> in the workspace directory, and fill in the following fields:</p> <pre><code>{\n\"exclude\": [\"__pypackages__\"]\n}\n</code></pre> <p>Then restart the language server or VS Code and you're good to go. In the future (microsoft/pylance-release#1150), maybe the problem will be solved.</p> Using Jupyter Notebook? <p>If you wish to use pdm to install jupyter notebook and use it in vscode in conjunction with the python extension:</p> <ol> <li>Use <code>pdm add notebook</code> or so to install notebook</li> <li>Add a <code>.env</code> file inside of your project directory with contents like the following:</li> </ol> <pre><code>PYTHONPATH=/your-workspace-path/__pypackages__/&lt;major&gt;.&lt;minor&gt;/lib\n</code></pre> <p>If the above still doesn't work, it's most likely because the environment variable is not properly loaded when the Notebook starts. There are two workarounds.</p> <ol> <li>Run <code>code .</code> in Terminal. It will open a new VSCode window in the current directory with the path set correctly. Use the Jupyter Notebook in the new window</li> <li>If you prefer not to open a new window, run the following at the beginning of your Jupyter Notebook to explicitly set the path:</li> </ol> <pre><code>import sys\nsys.path.append('/your-workspace-path/__pypackages__/&lt;major&gt;.&lt;minor&gt;/lib')\n</code></pre> <p>Reference Issue</p> PDM Task Provider <p>In addition, there is a VSCode Task Provider extension available for download.</p> <p>This makes it possible for VSCode to automatically detect pdm scripts so they can be run natively as VSCode Tasks.</p>"},{"location":"usage/pep582/#neovim","title":"Neovim","text":"<p>If using neovim-lsp with pyright and want your <code>__pypackages__</code> directory to be added to the path, you can add this to your project's <code>pyproject.toml</code>.</p> <pre><code>[tool.pyright]\nextraPaths = [\"__pypackages__/&lt;major.minor&gt;/lib/\"]\n</code></pre>"},{"location":"usage/pep582/#emacs","title":"Emacs","text":"<p>You have a few options, but basically you'll want to tell an LSP client to add <code>__pypackages__</code> to the paths it looks at. Here are a few options that are available:</p>"},{"location":"usage/pep582/#using-pyprojecttoml-and-pyright","title":"Using <code>pyproject.toml</code> and pyright","text":"<p>Add this to your project's <code>pyproject.toml</code>:</p> <pre><code>[tool.pyright]\nextraPaths = [\"__pypackages__/&lt;major.minor&gt;/lib/\"]\n</code></pre>"},{"location":"usage/pep582/#eglot-pyright","title":"eglot + pyright","text":"<p>Using pyright and eglot (included in Emacs 29), add the following to your config:</p> <pre><code>(defun get-pdm-packages-path ()\n\"For the current PDM project, find the path to the packages.\"\n(let ((packages-path (string-trim (shell-command-to-string \"pdm info --packages\"))))\n(concat packages-path \"/lib\")))\n\n(defun my/eglot-workspace-config (server)\n\"For the current PDM project, dynamically generate a python lsp config.\"\n`(:python\\.analysis (:extraPaths ,(vector (get-pdm-packages-path)))))\n\n(setq-default eglot-workspace-configuration #'my/eglot-workspace-config)\n</code></pre> <p>You'll want pyright installed either globally, or in your project (probably as a dev dependency). You can add this with, for example:</p> <pre><code>pdm add --dev --group devel pyright\n</code></pre>"},{"location":"usage/pep582/#lsp-mode-lsp-python-ms","title":"LSP-Mode + lsp-python-ms","text":"<p>Below is a sample code snippet showing how to make PDM work with lsp-python-ms in Emacs. Contributed by @linw1995.</p> <pre><code>  ;; TODO: Cache result\n(defun linw1995/pdm-get-python-executable (&amp;optional dir)\n(let ((pdm-get-python-cmd \"pdm info --python\"))\n(string-trim\n(shell-command-to-string\n(if dir\n(concat \"cd \"\ndir\n\" &amp;&amp; \"\npdm-get-python-cmd)\npdm-get-python-cmd)))))\n\n(defun linw1995/pdm-get-packages-path (&amp;optional dir)\n(let ((pdm-get-packages-cmd \"pdm info --packages\"))\n(concat (string-trim\n(shell-command-to-string\n(if dir\n(concat \"cd \"\ndir\n\" &amp;&amp; \"\npdm-get-packages-cmd)\npdm-get-packages-cmd)))\n\"/lib\")))\n\n(use-package lsp-python-ms\n:ensure t\n:init (setq lsp-python-ms-auto-install-server t)\n:hook (python-mode\n. (lambda ()\n(setq lsp-python-ms-python-executable (linw1995/pdm-get-python-executable))\n(setq lsp-python-ms-extra-paths (vector (linw1995/pdm-get-packages-path)))\n(require 'lsp-python-ms)\n(lsp))))  ; or lsp-deferred\n</code></pre>"},{"location":"usage/project/","title":"New Project","text":"<p>To start with, create a new project with <code>pdm init</code>:</p> <pre><code>mkdir my-project &amp;&amp; cd my-project\npdm init\n</code></pre> <p>You will need to answer a few questions, to help PDM to create a <code>pyproject.toml</code> file for you. For more usages of <code>pdm init</code>, please read Create your project from a template.</p>"},{"location":"usage/project/#choose-a-python-interpreter","title":"Choose a Python interpreter","text":"<p>At first, you need to choose a Python interpreter from a list of Python versions installed on your machine. The interpreter path will be stored in <code>.pdm-python</code> and used by subsequent commands. You can also change it later with <code>pdm use</code>.</p> <p>Alternatively, you can specify the Python interpreter path via <code>PDM_PYTHON</code> environment variable. When it is set, the path saved in <code>.pdm-python</code> will be ignored.</p>"},{"location":"usage/project/#virtualenv-or-not","title":"Virtualenv or not","text":"<p>After you select the Python interpreter, PDM will ask you whether you want to create a virtual environment for the project. If you choose yes, PDM will create a virtual environment in the project root directory, and use it as the Python interpreter for the project.</p> <p>If the selected Python interpreter is in a virtual environment, PDM will use it as the project environment and install dependencies into it. Otherwise, <code>__pypackages__</code> will be created in the project root and dependencies will be installed into it.</p> <p>For the difference between these two approaches, please refer to the corresponding sections in the docs:</p> <ul> <li>Virtualenv</li> <li><code>__pypackages__</code>(PEP 582)</li> </ul>"},{"location":"usage/project/#library-or-application","title":"Library or Application","text":"<p>A library and an application differ in many ways. In short, a library is a package that is intended to be installed and used by other projects. In most cases it also needs to be uploaded to PyPI. An application, on the other hand, is one that is directly facing end users and may need to be deployed into some production environments.</p> <p>In PDM, if you choose to create a library, PDM will add a <code>name</code>, <code>version</code> field to the <code>pyproject.toml</code> file, as well as a <code>[build-system]</code> table for the build backend, which is only useful if your project needs to be built and distributed. So you need to manually add these fields to <code>pyproject.toml</code> if you want to change the project from an application to a library. Also, a library project will be installed into the environment when you run <code>pdm install</code> or <code>pdm sync</code>, unless <code>--no-self</code> is specified.</p>"},{"location":"usage/project/#set-requires-python-value","title":"Set <code>requires-python</code> value","text":"<p>You need to set an appropriate <code>requires-python</code> value for your project. This is an important property that affects how dependencies are resolved. Basically, each package's <code>requires-python</code> must cover the project's <code>requires-python</code> range. For example, consider the following setup:</p> <ul> <li>Project: <code>requires-python = \"&gt;=3.9\"</code></li> <li>Package <code>foo</code>: <code>requires-python = \"&gt;=3.7,&lt;3.11\"</code></li> </ul> <p>Resolving the dependencies will cause a <code>ResolutionImpossible</code>:</p> <pre><code>Unable to find a resolution because the following dependencies don't work\non all Python versions defined by the project's `requires-python`\n</code></pre> <p>Because the dependency's <code>requires-python</code> is <code>&gt;=3.7,&lt;3.11</code>, it doesn't cover the project's <code>requires-python</code> range of <code>&gt;=3.9</code>. In other words, the project promises to work on Python 3.9, 3.10, 3.11 (and so on), but the dependency doesn't support Python 3.11 (or any higher). Since PDM creates a cross-platform lockfile that should work on all Python versions within the <code>requires-python</code> range, it can't find a valid resolution. To fix this, you need add a maximum version to <code>requires-python</code>, like <code>&gt;=3.9,&lt;3.11</code>.</p> <p>The value of <code>requires-python</code> is a version specifier as defined in PEP 440. Here are some examples:</p> <code>requires-python</code> Meaning <code>&gt;=3.7</code> Python 3.7 and above <code>&gt;=3.7,&lt;3.11</code> Python 3.7, 3.8, 3.9 and 3.10 <code>&gt;=3.6,!=3.8.*,!=3.9.*</code> Python 3.6 and above, except 3.8 and 3.9"},{"location":"usage/project/#working-with-older-python-versions","title":"Working with older Python versions","text":"<p>Although PDM run on Python 3.8 and above, you can still have lower Python versions for your working project. But remember, if your project is a library, which needs to be built, published or installed, you make sure the PEP 517 build backend being used supports the lowest Python version you need. For instance, the default backend <code>pdm-backend</code> only works on Python 3.7+, so if you run <code>pdm build</code> on a project with Python 3.6, you will get an error. Most modern build backends have dropped the support for Python 3.6 and lower, so it is highly recommended to upgrade the Python version to 3.7+. Here are the supported Python range for some commonly used build backends, we only list those that support PEP 621 since otherwise PDM can't work with them.</p> Backend Supported Python Support PEP 621 <code>pdm-backend</code> <code>&gt;=3.7</code> Yes <code>setuptools&gt;=60</code> <code>&gt;=3.7</code> Experimental <code>hatchling</code> <code>&gt;=3.7</code> Yes <code>flit-core&gt;=3.4</code> <code>&gt;=3.6</code> Yes <code>flit-core&gt;=3.2,&lt;3.4</code> <code>&gt;=3.4</code> Yes <p>Note that if your project is an application (i.e. without the <code>name</code> metadata), the above limitation of backends does not apply. Therefore, if you don't need a build backend you can use any Python version <code>&gt;=2.7</code>.</p>"},{"location":"usage/project/#import-the-project-from-other-package-managers","title":"Import the project from other package managers","text":"<p>If you are already using other package manager tools like Pipenv or Poetry, it is easy to migrate to PDM. PDM provides <code>import</code> command so that you don't have to initialize the project manually, it now supports:</p> <ol> <li>Pipenv's <code>Pipfile</code></li> <li>Poetry's section in <code>pyproject.toml</code></li> <li>Flit's section in <code>pyproject.toml</code></li> <li><code>requirements.txt</code> format used by pip</li> <li>setuptools <code>setup.py</code>(It requires <code>setuptools</code> to be installed in the project environment. You can do this by configuring <code>venv.with_pip</code> to <code>true</code> for venv and <code>pdm add setuptools</code> for <code>__pypackages__</code>)</li> </ol> <p>Also, when you are executing <code>pdm init</code> or <code>pdm install</code>, PDM can auto-detect possible files to import if your PDM project has not been initialized yet.</p> <p>Info</p> <p>Converting a <code>setup.py</code> will execute the file with the project interpreter. Make sure <code>setuptools</code> is installed with the interpreter and the <code>setup.py</code> is trusted.</p>"},{"location":"usage/project/#working-with-version-control","title":"Working with version control","text":"<p>You must commit the <code>pyproject.toml</code> file. You should commit the <code>pdm.lock</code> and <code>pdm.toml</code> file. Do not commit the <code>.pdm-python</code> file.</p> <p>The <code>pyproject.toml</code> file must be committed as it contains the project's build metadata and dependencies needed for PDM. It is also commonly used by other python tools for configuration. Read more about the <code>pyproject.toml</code> file at Pip documentation.</p> <p>You should be committing the <code>pdm.lock</code> file, by doing so you ensure that all installers are using the same versions of dependencies. To learn how to update dependencies see update existing dependencies.</p> <p><code>pdm.toml</code> contains some project-wide configuration and it may be useful to commit it for sharing.</p> <p><code>.pdm-python</code> stores the Python path used by the current project and doesn't need to be shared.</p>"},{"location":"usage/project/#show-the-current-python-environment","title":"Show the current Python environment","text":"<pre><code>$ pdm info\nPDM version:\n  2.0.0\nPython Interpreter:\n  /opt/homebrew/opt/python@3.9/bin/python3.9 (3.9)\nProject Root:\n  /Users/fming/wkspace/github/test-pdm\nProject Packages:\n  /Users/fming/wkspace/github/test-pdm/__pypackages__/3.9\n\n# Show environment info\n$ pdm info --env\n{\n\"implementation_name\": \"cpython\",\n  \"implementation_version\": \"3.8.0\",\n  \"os_name\": \"nt\",\n  \"platform_machine\": \"AMD64\",\n  \"platform_release\": \"10\",\n  \"platform_system\": \"Windows\",\n  \"platform_version\": \"10.0.18362\",\n  \"python_full_version\": \"3.8.0\",\n  \"platform_python_implementation\": \"CPython\",\n  \"python_version\": \"3.8\",\n  \"sys_platform\": \"win32\"\n}\n</code></pre> <p>This command is useful for checking which mode is being used by the project:</p> <ul> <li>If Project Packages is <code>None</code>, virtualenv mode is enabled.</li> <li>Otherwise, PEP 582 mode is enabled.</li> </ul> <p>Now, you have set up a new PDM project and get a <code>pyproject.toml</code> file. Refer to metadata section about how to write <code>pyproject.toml</code> properly.</p>"},{"location":"usage/publish/","title":"Build and Publish","text":"<p>If you are developing a library, after adding dependencies to your project, and finishing the coding, it's time to build and publish your package. It is as simple as one command:</p> <pre><code>pdm publish\n</code></pre> <p>This will automatically build a wheel and a source distribution(sdist), and upload them to the PyPI index.</p> <p>To specify another repository other than PyPI, use the <code>--repository</code> option, the parameter can be either the upload URL or the name of the repository stored in the config file.</p> <pre><code>pdm publish --repository testpypi\npdm publish --repository https://test.pypi.org/legacy/\n</code></pre>"},{"location":"usage/publish/#publish-with-trusted-publishers","title":"Publish with trusted publishers","text":"<p>You can configure trusted publishers for PyPI so that you don't need to expose the PyPI tokens in the release workflow. To do this, follow the guide to add a publisher and write the GitHub Actions workflow as below:</p> <pre><code>jobs:\npypi-publish:\nname: upload release to PyPI\nruns-on: ubuntu-latest\npermissions:\n# This permission is needed for private repositories.\ncontents: read\n# IMPORTANT: this permission is mandatory for trusted publishing\nid-token: write\nsteps:\n- uses: actions/checkout@v3\n\n- uses: pdm-project/setup-pdm@v3\n\n- name: Publish package distributions to PyPI\nrun: pdm publish\n</code></pre>"},{"location":"usage/publish/#build-and-publish-separately","title":"Build and publish separately","text":"<p>You can also build the package and upload it in two steps, to allow you to inspect the built artifacts before uploading.</p> <pre><code>pdm build\n</code></pre> <p>There are many options to control the build process, depending on the backend used. Refer to the build configuration section for more details.</p> <p>The artifacts will be created at <code>dist/</code> and able to upload to PyPI.</p> <pre><code>pdm publish --no-build\n</code></pre>"},{"location":"usage/scripts/","title":"PDM Scripts","text":"<p>Like <code>npm run</code>, with PDM, you can run arbitrary scripts or commands with local packages loaded.</p>"},{"location":"usage/scripts/#arbitrary-scripts","title":"Arbitrary Scripts","text":"<pre><code>pdm run flask run -p 54321\n</code></pre> <p>It will run <code>flask run -p 54321</code> in the environment that is aware of packages in your project environment.</p>"},{"location":"usage/scripts/#user-scripts","title":"User Scripts","text":"<p>PDM also supports custom script shortcuts in the optional <code>[tool.pdm.scripts]</code> section of <code>pyproject.toml</code>.</p> <p>Note</p> <p>The <code>[tool.pdm.scripts]</code> directory must not be confused with <code>[project.scripts]</code>. The latter is used to install a command as part of your package, as explained here.</p> <p>You can then run <code>pdm run &lt;script_name&gt;</code> to invoke the script in the context of your PDM project. For example:</p> <pre><code>[tool.pdm.scripts]\nstart = \"flask run -p 54321\"\n</code></pre> <p>And then in your terminal:</p> <pre><code>$ pdm run start\nFlask server started at http://127.0.0.1:54321\n</code></pre> <p>Any following arguments will be appended to the command:</p> <pre><code>$ pdm run start -h 0.0.0.0\nFlask server started at http://0.0.0.0:54321\n</code></pre> <p>Yarn-like script shortcuts</p> <p>There is a builtin shortcut making all scripts available as root commands as long as the script does not conflict with any builtin or plugin-contributed command. Said otherwise, if you have a <code>start</code> script, you can run both <code>pdm run start</code> and <code>pdm start</code>. But if you have an <code>install</code> script, only <code>pdm run install</code> will run it, <code>pdm install</code> will still run the builtin <code>install</code> command.</p> <p>PDM supports 4 types of scripts:</p>"},{"location":"usage/scripts/#cmd","title":"<code>cmd</code>","text":"<p>Plain text scripts are regarded as normal command, or you can explicitly specify it:</p> <pre><code>[tool.pdm.scripts]\nstart = {cmd = \"flask run -p 54321\"}\n</code></pre> <p>In some cases, such as when wanting to add comments between parameters, it might be more convenient to specify the command as an array instead of a string:</p> <pre><code>[tool.pdm.scripts]\nstart = {cmd = [\n\"flask\",\n\"run\",\n# Important comment here about always using port 54321\n\"-p\", \"54321\"\n]}\n</code></pre>"},{"location":"usage/scripts/#shell","title":"<code>shell</code>","text":"<p>Shell scripts can be used to run more shell-specific tasks, such as pipeline and output redirecting. This is basically run via <code>subprocess.Popen()</code> with <code>shell=True</code>:</p> <pre><code>[tool.pdm.scripts]\nfilter_error = {shell = \"cat error.log|grep CRITICAL &gt; critical.log\"}\n</code></pre>"},{"location":"usage/scripts/#call","title":"<code>call</code>","text":"<p>The script can be also defined as calling a python function in the form <code>&lt;module_name&gt;:&lt;func_name&gt;</code>:</p> <pre><code>[tool.pdm.scripts]\nfoobar = {call = \"foo_package.bar_module:main\"}\n</code></pre> <p>The function can be supplied with literal arguments:</p> <pre><code>[tool.pdm.scripts]\nfoobar = {call = \"foo_package.bar_module:main('dev')\"}\n</code></pre>"},{"location":"usage/scripts/#composite","title":"<code>composite</code>","text":"<p>This script kind execute other defined scripts:</p> <pre><code>[tool.pdm.scripts]\nlint = \"flake8\"\ntest = \"pytest\"\nall = {composite = [\"lint\", \"test\"]}\n</code></pre> <p>Running <code>pdm run all</code> will run <code>lint</code> first and then <code>test</code> if <code>lint</code> succeeded.</p> <p>Added in version 2.13.0</p> <p>To override the default behavior and continue the execution of the remaining scripts after a failure, set the <code>keep_going</code> option to <code>true</code>:</p> <pre><code>[tool.pdm.scripts]\nlint = \"flake8\"\ntest = \"pytest\"\nall = {composite = [\"lint\", \"test\"]}\nall.keep_going = true\n</code></pre> <p>If <code>keep_going</code> set to <code>true</code> return code of composite script is either '0' if all succeeded or the code of last failed individual script.</p> <p>You can also provide arguments to the called scripts:</p> <pre><code>[tool.pdm.scripts]\nlint = \"flake8\"\ntest = \"pytest\"\nall = {composite = [\"lint mypackage/\", \"test -v tests/\"]}\n</code></pre> <p>Note</p> <p>Argument passed on the command line are given to each called task.</p>"},{"location":"usage/scripts/#script-options","title":"Script Options","text":""},{"location":"usage/scripts/#env","title":"<code>env</code>","text":"<p>All environment variables set in the current shell can be seen by <code>pdm run</code> and will be expanded when executed. Besides, you can also define some fixed environment variables in your <code>pyproject.toml</code>:</p> <pre><code>[tool.pdm.scripts]\nstart.cmd = \"flask run -p 54321\"\nstart.env = {FOO = \"bar\", FLASK_ENV = \"development\"}\n</code></pre> <p>Note how we use TOML's syntax to define a composite dictionary.</p> <p>About environment variable substitution</p> <p>Variables in script specifications can be substituted in all script types. In <code>cmd</code> scripts, only <code>${VAR}</code> syntax is supported on all platforms, however in <code>shell</code> scripts, the syntax is platform-dependent. For example, Windows cmd uses <code>%VAR%</code> while bash uses <code>$VAR</code>.</p> <p>Note</p> <p>Environment variables specified on a composite task level will override those defined by called tasks.</p>"},{"location":"usage/scripts/#env_file","title":"<code>env_file</code>","text":"<p>You can also store all environment variables in a dotenv file and let PDM read it:</p> <pre><code>[tool.pdm.scripts]\nstart.cmd = \"flask run -p 54321\"\nstart.env_file = \".env\"\n</code></pre> <p>The variables within the dotenv file will not override any existing environment variables. If you want the dotenv file to override existing environment variables use the following:</p> <pre><code>[tool.pdm.scripts]\nstart.cmd = \"flask run -p 54321\"\nstart.env_file.override = \".env\"\n</code></pre> <p>Note</p> <p>A dotenv file specified on a composite task level will override those defined by called tasks.</p>"},{"location":"usage/scripts/#working_dir","title":"<code>working_dir</code>","text":"<p>Added in version 2.13.0</p> <p>You can set the current working directory for the script:</p> <pre><code>[tool.pdm.scripts]\nstart.cmd = \"flask run -p 54321\"\nstart.working_dir = \"subdir\"\n</code></pre> <p>Relative paths are resolved against the project root.</p>"},{"location":"usage/scripts/#site_packages","title":"<code>site_packages</code>","text":"<p>To make sure the running environment is properly isolated from the outer Python interpreter, site-packages from the selected interpreter WON'T be loaded into <code>sys.path</code>, unless any of the following conditions holds:</p> <ol> <li>The executable is from <code>PATH</code> but not inside the <code>__pypackages__</code> folder.</li> <li><code>-s/--site-packages</code> flag is following <code>pdm run</code>.</li> <li><code>site_packages = true</code> is in either the script table or the global setting key <code>_</code>.</li> </ol> <p>Note that site-packages will always be loaded if running with PEP 582 enabled(without the <code>pdm run</code> prefix).</p>"},{"location":"usage/scripts/#shared-options","title":"Shared Options","text":"<p>If you want the options to be shared by all tasks run by <code>pdm run</code>, you can write them under a special key <code>_</code> in <code>[tool.pdm.scripts]</code> table:</p> <pre><code>[tool.pdm.scripts]\n_.env_file = \".env\"\nstart = \"flask run -p 54321\"\nmigrate_db = \"flask db upgrade\"\n</code></pre> <p>Besides, inside the tasks, <code>PDM_PROJECT_ROOT</code> environment variable will be set to the project root.</p>"},{"location":"usage/scripts/#arguments-placeholder","title":"Arguments placeholder","text":"<p>By default, all user provided extra arguments are simply appended to the command (or to all the commands for <code>composite</code> tasks).</p> <p>If you want more control over the user provided extra arguments, you can use the <code>{args}</code> placeholder. It is available for all script types and will be interpolated properly for each:</p> <pre><code>[tool.pdm.scripts]\ncmd = \"echo '--before {args} --after'\"\nshell = {shell = \"echo '--before {args} --after'\"}\ncomposite = {composite = [\"cmd --something\", \"shell {args}\"]}\n</code></pre> <p>will produce the following interpolations (those are not real scripts, just here to illustrate the interpolation):</p> <pre><code>$ pdm run cmd --user --provided\n--before --user --provided --after\n$ pdm run cmd\n--before --after\n$ pdm run shell --user --provided\n--before --user --provided --after\n$ pdm run shell\n--before --after\n$ pdm run composite --user --provided\ncmd --something\nshell --before --user --provided --after\n$ pdm run composite\ncmd --something\nshell --before --after\n</code></pre> <p>You may optionally provide default values that will be used if no user arguments are provided:</p> <pre><code>[tool.pdm.scripts]\ntest = \"echo '--before {args:--default --value} --after'\"\n</code></pre> <p>will produce the following:</p> <pre><code>$ pdm run test --user --provided\n--before --user --provided --after\n$ pdm run test\n--before --default --value --after\n</code></pre> <p>Note</p> <p>As soon a placeholder is detected, arguments are not appended anymore. This is important for <code>composite</code> scripts because if a placeholder is detected on one of the subtasks, none for the subtasks will have the arguments appended, you need to explicitly pass the placeholder to every nested command requiring it.</p> <p>Note</p> <p><code>call</code> scripts don't support the <code>{args}</code> placeholder as they have access to <code>sys.argv</code> directly to handle such complexe cases and more.</p>"},{"location":"usage/scripts/#pdm-placeholder","title":"<code>{pdm}</code> placeholder","text":"<p>Sometimes you may have multiple PDM installations, or <code>pdm</code> installed with a different name. This could for example occur in a CI/CD situation, or when working with different PDM versions in different repos. To make your scripts more robust you can use <code>{pdm}</code> to use the PDM entrypoint executing the script. This will expand to <code>{sys.executable} -m pdm</code>.</p> <p><pre><code>[tool.pdm.scripts]\nwhoami = { shell = \"echo `{pdm} -V` was called as '{pdm} -V'\" }\n</code></pre> will produce the following output: <pre><code>$ pdm whoami\nPDM, version 0.1.dev2501+g73651b7.d20231115 was called as /usr/bin/python3 -m pdm -V\n\n$ pdm2.8 whoami\nPDM, version 2.8.0 was called as &lt;snip&gt;/venvs/pdm2-8/bin/python -m pdm -V\n</code></pre></p> <p>Note</p> <p>While the above example uses PDM 2.8, this functionality was introduced in the 2.10 series and only backported for the showcase.</p>"},{"location":"usage/scripts/#show-the-list-of-scripts","title":"Show the List of Scripts","text":"<p>Use <code>pdm run --list/-l</code> to show the list of available script shortcuts:</p> <pre><code>$ pdm run --list\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Name        \u2502 Type  \u2502 Description               \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 test_cmd    \u2502 cmd   \u2502 flask db upgrade          \u2502\n\u2502 test_script \u2502 call  \u2502 call a python function    \u2502\n\u2502 test_shell  \u2502 shell \u2502 shell command             \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n</code></pre> <p>You can add an <code>help</code> option with the description of the script, and it will be displayed in the <code>Description</code> column in the above output.</p> <p>Note</p> <p>Tasks with a name starting with an underscore (<code>_</code>) are considered internal (helpers...) and are not shown in the listing.</p>"},{"location":"usage/scripts/#pre-post-scripts","title":"Pre &amp; Post Scripts","text":"<p>Like <code>npm</code>, PDM also supports tasks composition by pre and post scripts, pre script will be run before the given task and post script will be run after.</p> <pre><code>[tool.pdm.scripts]\npre_compress = \"{{ Run BEFORE the `compress` script }}\"\ncompress = \"tar czvf compressed.tar.gz data/\"\npost_compress = \"{{ Run AFTER the `compress` script }}\"\n</code></pre> <p>In this example, <code>pdm run compress</code> will run all these 3 scripts sequentially.</p> <p>The pipeline fails fast</p> <p>In a pipeline of pre - self - post scripts, a failure will cancel the subsequent execution.</p>"},{"location":"usage/scripts/#hook-scripts","title":"Hook Scripts","text":"<p>Under certain situations PDM will look for some special hook scripts for execution:</p> <ul> <li><code>post_init</code>: Run after <code>pdm init</code></li> <li><code>pre_install</code>: Run before installing packages</li> <li><code>post_install</code>: Run after packages are installed</li> <li><code>pre_lock</code>: Run before dependency resolution</li> <li><code>post_lock</code>: Run after dependency resolution</li> <li><code>pre_build</code>: Run before building distributions</li> <li><code>post_build</code>: Run after distributions are built</li> <li><code>pre_publish</code>: Run before publishing distributions</li> <li><code>post_publish</code>: Run after distributions are published</li> <li><code>pre_script</code>: Run before any script</li> <li><code>post_script</code>: Run after any script</li> <li><code>pre_run</code>: Run once before run script invocation</li> <li><code>post_run</code>: Run once after run script invocation</li> </ul> <p>Note</p> <p>Pre &amp; post scripts can't receive any arguments.</p> <p>Avoid name conflicts</p> <p>If there exists an <code>install</code> scripts under <code>[tool.pdm.scripts]</code> table, <code>pre_install</code> scripts can be triggered by both <code>pdm install</code> and <code>pdm run install</code>. So it is recommended to not use the preserved names.</p> <p>Note</p> <p>Composite tasks can also have pre and post scripts. Called tasks will run their own pre and post scripts.</p>"},{"location":"usage/scripts/#skipping-scripts","title":"Skipping scripts","text":"<p>Because, sometimes it is desirable to run a script but without its hooks or pre and post scripts, there is a <code>--skip=:all</code> which will disable all hooks, pre and post. There is also <code>--skip=:pre</code> and <code>--skip=:post</code> allowing to respectively skip all <code>pre_*</code> hooks and all <code>post_*</code> hooks.</p> <p>It is also possible to need a pre script but not the post one, or to need all tasks from a composite tasks except one. For those use cases, there is a finer grained <code>--skip</code> parameter accepting a list of tasks or hooks name to exclude.</p> <pre><code>pdm run --skip pre_task1,task2 my-composite\n</code></pre> <p>This command will run the <code>my-composite</code> task and skip the <code>pre_task1</code> hook as well as the <code>task2</code> and its hooks.</p> <p>You can also provide you skip list in <code>PDM_SKIP_HOOKS</code> environment variable but it will be overridden as soon as the <code>--skip</code> parameter is provided.</p> <p>There is more details on hooks and pre/post scripts behavior on the dedicated hooks page.</p>"},{"location":"usage/template/","title":"Create Project From a Template","text":"<p>Similar to <code>yarn create</code> and <code>npm create</code>, PDM also supports initializing or creating a project from a template. The template is given as a positional argument of <code>pdm init</code>, in one of the following forms:</p> <ul> <li><code>pdm init django</code> - Initialize the project from the template <code>https://github.com/pdm-project/template-django</code></li> <li><code>pdm init https://github.com/frostming/pdm-template-django</code> - Initialize the project from a Git URL. Both HTTPS and SSH URL are acceptable.</li> <li><code>pdm init django@v2</code> - To check out the specific branch or tag. Full Git URL also supports it.</li> <li><code>pdm init /path/to/template</code> - Initialize the project from a template directory on local filesystem.</li> <li><code>pdm init minimal</code> - Initialize with the builtin \"minimal\" template, that only generates a <code>pyproject.toml</code>.</li> </ul> <p>And <code>pdm init</code> will use the default template built in.</p> <p>The project will be initialized at the current directory, existing files with the same name will be overwritten. You can also use the <code>-p &lt;path&gt;</code> option to create a project at a new path.</p>"},{"location":"usage/template/#contribute-a-template","title":"Contribute a template","text":"<p>According to the first form of the template argument, <code>pdm init &lt;name&gt;</code> will refer to the template repository located at <code>https://github.com/pdm-project/template-&lt;name&gt;</code>. To contribute a template, you can create a template repository and establish a request to transfer the ownership to <code>pdm-project</code> organization(it can be found at the bottom of the repository settings page). The administrators of the organization will review the request and complete the subsequent steps. You will be added as the repository maintainer if the transfer is accepted.</p>"},{"location":"usage/template/#requirements-for-a-template","title":"Requirements for a template","text":"<p>A template repository must be a pyproject-based project, which contains a <code>pyproject.toml</code> file with PEP-621 compliant metadata. No other special config files are required.</p>"},{"location":"usage/template/#project-name-replacement","title":"Project name replacement","text":"<p>On initialization, the project name in the template will be replaced by the name of the new project. This is done by a recursive full-text search and replace. The import name, which is derived from the project name by replacing all non-alphanumeric characters with underscores and lowercasing, will also be replaced in the same way.</p> <p>For example, if the project name is <code>foo-project</code> in the template and you want to initialize a new project named <code>bar-project</code>, the following replacements will be made:</p> <ul> <li><code>foo-project</code> -&gt; <code>bar-project</code> in all <code>.md</code> files and <code>.rst</code> files</li> <li><code>foo_project</code> -&gt; <code>bar_project</code> in all <code>.py</code> files</li> <li><code>foo_project</code> -&gt; <code>bar_project</code> in the directory name</li> <li><code>foo_project.py</code> -&gt; <code>bar_project.py</code> in the file name</li> </ul> <p>Therefore, we don't support name replacement if the import name isn't derived from the project name.</p>"},{"location":"usage/template/#use-other-project-generators","title":"Use other project generators","text":"<p>If you are seeking for a more powerful project generator, you can use cookiecutter via <code>--cookiecutter</code> option and copier via <code>--copier</code> option.</p> <p>You need to install <code>cookiecutter</code> and <code>copier</code> respectively to use them. You can do this by running <code>pdm self add &lt;package&gt;</code>. To use them:</p> <pre><code>pdm init --cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python\n# or\npdm init --copier gh:pawamoy/copier-pdm --UNSAFE\n</code></pre>"},{"location":"usage/venv/","title":"Working with Virtual Environments","text":"<p>When you run <code>pdm init</code> command, PDM will ask for the Python interpreter to use in the project, which is the base interpreter to install dependencies and run tasks.</p> <p>Compared to PEP 582, virtual environments are considered more mature and have better support in the Python ecosystem as well as IDEs. Therefore, virtualenv is the default mode if not configured otherwise.</p> <p>Virtual environments will be used if the project interpreter (the interpreter stored in <code>.pdm-python</code>, which can be checked by <code>pdm info</code>) is from a virtualenv.</p>"},{"location":"usage/venv/#virtualenv-auto-creation","title":"Virtualenv auto-creation","text":"<p>By default, PDM prefers to use the virtualenv layout as other package managers do. When you run <code>pdm install</code> the first time on a new PDM-managed project, whose Python interpreter is not decided yet, PDM will create a virtualenv in <code>&lt;project_root&gt;/.venv</code>, and install dependencies into it. In the interactive session of <code>pdm init</code>, PDM will also ask to create a virtualenv for you.</p> <p>You can choose the backend used by PDM to create a virtualenv. Currently it supports three backends:</p> <ul> <li><code>virtualenv</code>(default)</li> <li><code>venv</code></li> <li><code>conda</code></li> </ul> <p>You can change it by <code>pdm config venv.backend [virtualenv|venv|conda]</code>.</p>"},{"location":"usage/venv/#create-a-virtualenv-yourself","title":"Create a virtualenv yourself","text":"<p>You can create more than one virtualenvs with whatever Python version you want.</p> <pre><code># Create a virtualenv based on 3.8 interpreter\n$ pdm venv create 3.8\n# Assign a different name other than the version string\n$ pdm venv create --name for-test 3.8\n# Use venv as the backend to create, support 3 backends: virtualenv(default), venv, conda\n$ pdm venv create --with venv 3.9\n</code></pre>"},{"location":"usage/venv/#the-location-of-virtualenvs","title":"The location of virtualenvs","text":"<p>If no <code>--name</code> is given, PDM will create the venv in <code>&lt;project_root&gt;/.venv</code>. Otherwise, virtualenvs go to the location specified by the <code>venv.location</code> configuration. They are named as <code>&lt;project_name&gt;-&lt;path_hash&gt;-&lt;name_or_python_version&gt;</code> to avoid name collision. You can disable the in-project virtualenv creation by <code>pdm config venv.in_project false</code>. And all virtualenvs will be created under <code>venv.location</code>.</p>"},{"location":"usage/venv/#reuse-the-virtualenv-you-created-elsewhere","title":"Reuse the virtualenv you created elsewhere","text":"<p>You can tell PDM to use a virtualenv you created in preceding steps, with <code>pdm use</code>:</p> <pre><code>pdm use -f /path/to/venv\n</code></pre>"},{"location":"usage/venv/#virtualenv-auto-detection","title":"Virtualenv auto-detection","text":"<p>When no interpreter is stored in the project config or <code>PDM_IGNORE_SAVED_PYTHON</code> env var is set, PDM will try to detect possible virtualenvs to use:</p> <ul> <li><code>venv</code>, <code>env</code>, <code>.venv</code> directories in the project root</li> <li>The currently activated virtualenv, unless <code>PDM_IGNORE_ACTIVE_VENV</code> is set</li> </ul>"},{"location":"usage/venv/#list-all-virtualenvs-created-with-this-project","title":"List all virtualenvs created with this project","text":"<pre><code>$ pdm venv list\nVirtualenvs created with this project:\n\n-  3.8.6: C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-3.8.6\n-  for-test: C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-for-test\n-  3.9.1: C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-3.9.1\n</code></pre>"},{"location":"usage/venv/#show-the-path-or-python-interpreter-of-a-virtualenv","title":"Show the path or python interpreter of a virtualenv","text":"<pre><code>$ pdm venv --path for-test\n$ pdm venv --python for-test\n</code></pre>"},{"location":"usage/venv/#remove-a-virtualenv","title":"Remove a virtualenv","text":"<pre><code>$ pdm venv remove for-test\nVirtualenvs created with this project:\nWill remove: C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-for-test, continue? [y/N]:y\nRemoved C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-for-test\n</code></pre>"},{"location":"usage/venv/#activate-a-virtualenv","title":"Activate a virtualenv","text":"<p>Instead of spawning a subshell like what <code>pipenv</code> and <code>poetry</code> do, <code>pdm venv</code> doesn't create the shell for you but print the activate command to the console. In this way you won't leave the current shell. You can then feed the output to <code>eval</code> to activate the virtualenv:</p> bash/csh/zshFishPowershell <pre><code>$ eval $(pdm venv activate for-test)\n(test-project-for-test) $  # Virtualenv entered\n</code></pre> <pre><code>$ eval (pdm venv activate for-test)\n</code></pre> <pre><code>PS1&gt; Invoke-Expression (pdm venv activate for-test)\n</code></pre> <p>Additionally, if the project interpreter is a venv Python, you can omit the name argument following activate.</p> <p>Note</p> <p><code>venv activate</code> does not switch the Python interpreter used by the project. It only changes the shell by injecting the virtualenv paths to environment variables. For the forementioned purpose, use the <code>pdm use</code> command.</p> <p>For more CLI usage, see the <code>pdm venv</code> documentation.</p> <p>Looking for <code>pdm shell</code>?</p> <p>PDM doesn't provide a <code>shell</code> command because many fancy shell functions may not work perfectly in a subshell, which brings a maintenance burden to support all the corner cases. However, you can still gain the ability via the following ways:</p> <ul> <li>Use <code>pdm run $SHELL</code>, this will spawn a subshell with the environment variables set properly. The subshell can be quit with <code>exit</code> or <code>Ctrl+D</code>.</li> <li>Add a shell function to activate the virtualenv, here is an example of BASH function that also works on ZSH:</li> </ul> <pre><code>pdm() {\nlocal command=$1\n\nif [[ \"$command\" == \"shell\" ]]; then\neval $(pdm venv activate)\nelse\ncommand pdm $@\nfi\n}\n</code></pre> <p>Copy and paste this function to your <code>~/.bashrc</code> file and restart your shell. </p> <p>For <code>fish</code> shell you can put the following into your <code>~/fish/config.fish</code> or in <code>~/.config/fish/config.fish</code></p> <pre><code>  function pdm\n      set cmd $argv[1]\n\n      if test \"$cmd\" = \"shell\"\n          eval (pdm venv activate)\n      else\n          command pdm $argv\n      end\n  end\n</code></pre> <p>Now you can run <code>pdm shell</code> to activate the virtualenv.   The virtualenv can be deactivated with <code>deactivate</code> command as usual.</p>"},{"location":"usage/venv/#prompt-customization","title":"Prompt customization","text":"<p>By default when you activate a virtualenv, the prompt will show: <code>{project_name}-{python_version}</code>.</p> <p>For example if your project is named <code>test-project</code>:</p> <pre><code>$ eval $(pdm venv activate for-test)\n(test-project-3.10) $  # {project_name} == test-project and {python_version} == 3.10\n</code></pre> <p>The format can be customized before virtualenv creation with the <code>venv.prompt</code> configuration or <code>PDM_VENV_PROMPT</code> environment variable (before a <code>pdm init</code> or <code>pdm venv create</code>). Available variables are:</p> <ul> <li><code>project_name</code>: name of your project</li> <li><code>python_version</code>: version of Python (used by the virtualenv)</li> </ul> <pre><code>$ PDM_VENV_PROMPT='{project_name}-py{python_version}' pdm venv create --name test-prompt\n$ eval $(pdm venv activate test-prompt)\n(test-project-py3.10) $\n</code></pre>"},{"location":"usage/venv/#run-a-command-in-a-virtual-environment-without-activating-it","title":"Run a command in a virtual environment without activating it","text":"<pre><code># Run a script\n$ pdm run --venv test test\n# Install packages\n$ pdm sync --venv test\n# List the packages installed\n$ pdm list --venv test\n</code></pre> <p>There are other commands supporting <code>--venv</code> flag or <code>PDM_IN_VENV</code> environment variable, see the CLI reference. You should create the virtualenv with <code>pdm venv create --name &lt;name&gt;</code> before using this feature.</p>"},{"location":"usage/venv/#switch-to-a-virtualenv-as-the-project-environment","title":"Switch to a virtualenv as the project environment","text":"<p>By default, if you use <code>pdm use</code> and select a non-venv Python, the project will be switched to PEP 582 mode. We also allow you to switch to a named virtual environment via the <code>--venv</code> flag:</p> <pre><code># Switch to a virtualenv named test\n$ pdm use --venv test\n# Switch to the in-project venv located at $PROJECT_ROOT/.venv\n$ pdm use --venv in-project\n</code></pre>"},{"location":"usage/venv/#disable-virtualenv-mode","title":"Disable virtualenv mode","text":"<p>You can disable the auto-creation and auto-detection for virtualenv by <code>pdm config python.use_venv false</code>. If venv is disabled, PEP 582 mode will always be used even if the selected interpreter is from a virtualenv.</p>"},{"location":"usage/venv/#including-pip-in-your-virtual-environment","title":"Including pip in your virtual environment","text":"<p>By default PDM will not include <code>pip</code> in virtual environments. This increases isolation by ensuring that only your dependencies are installed in the virtual environment.</p> <p>To install <code>pip</code> once (if for example you want to install arbitrary dependencies in CI) you can run:</p> <pre><code># Install pip in the virtual environment\n$ pdm run python -m ensurepip\n# Install arbitrary dependencies\n# These dependencies are not checked for conflicts against lockfile dependencies!\n$ pdm run python -m pip install coverage\n</code></pre> <p>Or you can create the virtual environment with <code>--with-pip</code>:</p> <pre><code>$ pdm venv create --with-pip 3.9\n</code></pre> <p>See the ensurepip docs for more details on <code>ensurepip</code>.</p> <p>If you want to permanently configure PDM to include <code>pip</code> in virtual environments you can use the <code>venv.with_pip</code> configuration.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":""},{"location":"#introduction","title":"Introduction","text":"<p>PDM, as described, is a modern Python package and dependency manager supporting the latest PEP standards. But it is more than a package manager. It boosts your development workflow in various aspects.</p>"},{"location":"#feature-highlights","title":"Feature highlights","text":"<ul> <li>Simple and fast dependency resolver, mainly for large binary distributions.</li> <li>A PEP 517 build backend.</li> <li>PEP 621 project metadata.</li> <li>Flexible and powerful plug-in system.</li> <li>Versatile user scripts.</li> <li>Opt-in centralized installation cache like pnpm.</li> </ul>"},{"location":"#installation","title":"Installation","text":"<p>PDM requires Python 3.8+ to be installed. It works on multiple platforms including Windows, Linux and macOS.</p> <p>Note</p> <p>You can still have your project working on lower Python versions, read how to do it here.</p>"},{"location":"#recommended-installation-method","title":"Recommended installation method","text":"<p>PDM requires python version 3.8 or higher.</p> <p>Like Pip, PDM provides an installation script that will install PDM into an isolated environment.</p> Linux/MacWindows <pre><code>curl -sSL https://pdm-project.org/install-pdm.py | python3 -\n</code></pre> <pre><code>(Invoke-WebRequest -Uri https://pdm-project.org/install-pdm.py -UseBasicParsing).Content | py -\n</code></pre> <p>For security reasons, you should verify the checksum of <code>install-pdm.py</code>. It can be downloaded from install-pdm.py.sha256.</p> <p>For example, on Linux/Mac:</p> <pre><code>curl -sSLO https://pdm-project.org/install-pdm.py\ncurl -sSL https://pdm-project.org/install-pdm.py.sha256 | shasum -a 256 -c -\n# Run the installer\npython3 install-pdm.py [options]\n</code></pre> <p>The installer will install PDM into the user site and the location depends on the system:</p> <ul> <li><code>$HOME/.local/bin</code> for Unix</li> <li><code>$HOME/Library/Python/&lt;version&gt;/bin</code> for MacOS</li> <li><code>%APPDATA%\\Python\\Scripts</code> on Windows</li> </ul> <p>You can pass additional options to the script to control how PDM is installed:</p> <pre><code>usage: install-pdm.py [-h] [-v VERSION] [--prerelease] [--remove] [-p PATH] [-d DEP]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v VERSION, --version VERSION | envvar: PDM_VERSION\n                        Specify the version to be installed, or HEAD to install from the main branch\n  --prerelease | envvar: PDM_PRERELEASE    Allow prereleases to be installed\n  --remove | envvar: PDM_REMOVE            Remove the PDM installation\n  -p PATH, --path PATH | envvar: PDM_HOME  Specify the location to install PDM\n  -d DEP, --dep DEP | envvar: PDM_DEPS     Specify additional dependencies, can be given multiple times\n</code></pre> <p>You can either pass the options after the script or set the env var value.</p>"},{"location":"#other-installation-methods","title":"Other installation methods","text":"HomebrewScooppipxpipasdfinside project <pre><code>brew install pdm\n</code></pre> <pre><code>scoop bucket add frostming https://github.com/frostming/scoop-frostming.git\nscoop install pdm\n</code></pre> <pre><code>pipx install pdm\n</code></pre> <p>Install the head version of GitHub repository. Make sure you have installed Git LFS on your system.</p> <pre><code>pipx install git+https://github.com/pdm-project/pdm.git@main#egg=pdm\n</code></pre> <p>To install PDM with all features:</p> <pre><code>pipx install pdm[all]\n</code></pre> <p>See also: https://pypa.github.io/pipx/</p> <pre><code>pip install --user pdm\n</code></pre> <p>Assuming you have asdf installed. <pre><code>asdf plugin add pdm\nasdf local pdm latest\nasdf install pdm\n</code></pre></p> <p>By copying the Pyprojectx wrapper scripts to a project, you can install PDM as (npm-style) dev dependency inside that project. This allows different projects/branches to use different PDM versions.</p> <p>To initialize a new or existing project, cd into the project folder and:</p> Linux/MacWindows <pre><code>curl -LO https://github.com/pyprojectx/pyprojectx/releases/latest/download/wrappers.zip &amp;&amp; unzip wrappers.zip &amp;&amp; rm -f wrappers.zip\n./pw --add pdm\n</code></pre> <pre><code>Invoke-WebRequest https://github.com/pyprojectx/pyprojectx/releases/latest/download/wrappers.zip -OutFile wrappers.zip; Expand-Archive -Path wrappers.zip -DestinationPath .; Remove-Item -Path wrappers.zip\n.\\pw --add pdm\n</code></pre> <p>When installing pdm with this method, you need to run all <code>pdm</code> commands through the <code>pw</code> wrapper:</p> Linux/Mac/Windows <pre><code>./pw pdm install\n</code></pre>"},{"location":"#update-the-pdm-version","title":"Update the PDM version","text":"<pre><code>pdm self update\n</code></pre>"},{"location":"#packaging-status","title":"Packaging Status","text":""},{"location":"#shell-completion","title":"Shell Completion","text":"<p>PDM supports generating completion scripts for Bash, Zsh, Fish or Powershell. Here are some common locations for each shell:</p> BashZshFishPowershell <pre><code>pdm completion bash &gt; /etc/bash_completion.d/pdm.bash-completion\n</code></pre> <pre><code># Make sure ~/.zfunc is added to fpath, before compinit.\npdm completion zsh &gt; ~/.zfunc/_pdm\n</code></pre> <p>Oh-My-Zsh:</p> <pre><code>mkdir $ZSH_CUSTOM/plugins/pdm\npdm completion zsh &gt; $ZSH_CUSTOM/plugins/pdm/_pdm\n</code></pre> <p>Then make sure pdm plugin is enabled in ~/.zshrc</p> <pre><code>pdm completion fish &gt; ~/.config/fish/completions/pdm.fish\n</code></pre> <pre><code># Create a directory to store completion scripts\nmkdir $PROFILE\\..\\Completions\necho @'\nGet-ChildItem \"$PROFILE\\..\\Completions\\\" | ForEach-Object {\n    . $_.FullName\n}\n'@ | Out-File -Append -Encoding utf8 $PROFILE\n# Generate script\nSet-ExecutionPolicy Unrestricted -Scope CurrentUser\npdm completion powershell | Out-File -Encoding utf8 $PROFILE\\..\\Completions\\pdm_completion.ps1\n</code></pre>"},{"location":"#virtualenv-and-pep-582","title":"Virtualenv and PEP 582","text":"<p>PDM offers experimental support for PEP 582 as an opt-in feature, in addition to virtualenv management. Although the Python Steering Council has rejected PEP 582, you can still test it out using PDM.</p> <p>To learn more about the two modes, refer to the relevant chapters on Working with virtualenv and Working with PEP 582.</p>"},{"location":"#pdm-eco-system","title":"PDM Eco-system","text":"<p>Awesome PDM is a curated list of awesome PDM plugins and resources.</p>"},{"location":"#sponsors","title":"Sponsors","text":""},{"location":"dev/benchmark/","title":"Benchmark","text":"<p>This page has been removed, please visit https://lincolnloop.github.io/python-package-manager-shootout/ for a detailed benchmark report.</p>"},{"location":"dev/changelog/","title":"Changelog","text":"<p>Attention</p> <p>Major and minor releases also include changes listed within prior beta releases.</p>"},{"location":"dev/changelog/#release-v2124-2024-02-26","title":"Release v2.12.4 (2024-02-26)","text":""},{"location":"dev/changelog/#features-improvements","title":"Features &amp; Improvements","text":"<ul> <li>Use env PDM_NO_EDITABLE as the default value for --no-editable option. #2613</li> </ul>"},{"location":"dev/changelog/#bug-fixes","title":"Bug Fixes","text":"<ul> <li>Reset project.environment when importing from setup.py, to fix resolution error. #2608</li> <li>Do not fetch package hashes when <code>--frozen-lockfile</code> is passed. #2630</li> <li>Make sure non-venv interpreters are used by venv creator. #2631</li> <li>Don't cause a hard failure if the local directory doesn't exist. #2650</li> </ul>"},{"location":"dev/changelog/#documentation","title":"Documentation","text":"<ul> <li>Fix the default value for negative CLI flags. #2642</li> <li>Auto-gen configuration reference documentation. #2645</li> </ul>"},{"location":"dev/changelog/#release-v2123-2024-02-01","title":"Release v2.12.3 (2024-02-01)","text":""},{"location":"dev/changelog/#bug-fixes_1","title":"Bug Fixes","text":"<ul> <li>fix the package-type fixer won't update toml properly for \"Nested Section Ordering Issue in TOML\". #2578</li> <li>Unable to force override a package if the package is required with extras. #2586</li> <li>Failed to clone template repository if the URL contains the rev part. #2597</li> <li>Handle legacy specifiers when converting from poetry project. #2599</li> </ul>"},{"location":"dev/changelog/#documentation_1","title":"Documentation","text":"<ul> <li>Fix typo in template docs #2588</li> </ul>"},{"location":"dev/changelog/#release-v2122-2024-01-21","title":"Release v2.12.2 (2024-01-21)","text":""},{"location":"dev/changelog/#bug-fixes_2","title":"Bug Fixes","text":"<ul> <li>Fix the auto fixer for package-type. #2564</li> <li>Fix the wrong installation destination for header files when installing build requirements. #2573</li> <li>Install header files into package namespace under <code>include</code> directory. #2574</li> </ul>"},{"location":"dev/changelog/#release-v2121-2024-01-17","title":"Release v2.12.1 (2024-01-17)","text":""},{"location":"dev/changelog/#bug-fixes_3","title":"Bug Fixes","text":"<ul> <li>Hotfix: missing <code>identifier</code> attribute for package type fixer. #2564</li> </ul>"},{"location":"dev/changelog/#release-v2120-2024-01-17","title":"Release v2.12.0 (2024-01-17)","text":""},{"location":"dev/changelog/#features-improvements_1","title":"Features &amp; Improvements","text":"<ul> <li>Allow excluding packages from the lockfile via <code>tool.pdm.resolution.excludes</code> setting, the dependencies will also be skipped. #1316</li> <li>Rename <code>--no-lock</code> option to <code>--frozen-lockfile</code>. #2496</li> <li>Add <code>--no-hashes</code> as the recommended option name in favor of <code>--without-hashes</code> for <code>pdm export</code> command. #2497</li> <li>Add <code>--no-markers</code> to <code>export</code> command to exclude markers from the output. #2497</li> <li>Allow initializing a project without extra project files, with a new builtin template \"minimal\". Run it with <code>pdm init minimal</code>. #2543</li> <li>Change the warning category emitted by <code>deprecated_warning()</code> to <code>PDMDeprecationWarning</code>. #2547</li> <li>Prereleases will be allowed if a prerelease version is pinned in the lockfile. This can be disabled by passing <code>--stable</code> option. #2552</li> <li>Change <code>tracked_names</code> argument to keyword-only. Move <code>allow_prereleases</code> setting to <code>tool.pdm.resolution</code> table. #2552</li> <li>Rename the <code>preferred_pins</code> argument of provider classes to <code>locked_candidates</code>, and deprecate the old name. #2552</li> <li>Rename the <code>package-type</code> field under <code>tool.pdm</code> settings table to <code>distribution</code> to make it more clear. #2564</li> </ul>"},{"location":"dev/changelog/#bug-fixes_4","title":"Bug Fixes","text":"<ul> <li><code>tool.pdm.resolution</code> settings won't be honored when installing dependencies into the build environment. #1316</li> <li>Fixed pdm list output containing full license text in some cases #2538</li> <li>Fix the environment variable substitution for <code>cmd</code> scripts. #2542</li> <li>Allow normal extension modules in wheel tags when the python is debug build. #2548</li> <li>Don't use pypi.org when pypi.url is set. #2560</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations","title":"Removals and Deprecations","text":"<ul> <li>Remove deprecated methods from <code>Project</code>. Remove deprecated helper functions from <code>actions.py</code>. #2547</li> </ul>"},{"location":"dev/changelog/#release-v2112-2024-01-02","title":"Release v2.11.2 (2024-01-02)","text":""},{"location":"dev/changelog/#bug-fixes_5","title":"Bug Fixes","text":"<ul> <li>Fix a KeyError raised when resolving a URL dependency without package name given. #2488</li> <li><code>pdm update --update-eager</code> can hit InconsistentCandidate error when dependency is included both through default dependencies and extra. #2495</li> <li><code>pdm install</code> should not warn when overwriting its own symlinks on <code>install</code>/<code>update</code>. #2502</li> <li>Fix a bug that candidates without local version are rejected when the local version is pinned. #2507</li> </ul>"},{"location":"dev/changelog/#documentation_2","title":"Documentation","text":"<ul> <li>Add maturin as a compatible build backend in the docs. #2510</li> </ul>"},{"location":"dev/changelog/#release-v2111-2023-12-14","title":"Release v2.11.1 (2023-12-14)","text":""},{"location":"dev/changelog/#bug-fixes_6","title":"Bug Fixes","text":"<ul> <li>Update candidate names before resolving markers, to fix a KeyError when the requirement is not named. #2488</li> <li>Fix a KeyError when resolving packages that have parents that are no longer needed. #2489</li> </ul>"},{"location":"dev/changelog/#release-v2110-2023-12-14","title":"Release v2.11.0 (2023-12-14)","text":""},{"location":"dev/changelog/#features-improvements_2","title":"Features &amp; Improvements","text":"<ul> <li>Officially drop the support for Python 3.7.</li> <li>Allow exporting current project as editable dependency with <code>pdm export</code>. #1910</li> <li>Improve the lockfile compatibility checking by using 3-digit version numbers. This can distinguish forward-compatibility and backward-compatibility. #2164</li> <li>Add <code>--skip-existing</code> to <code>pdm publish</code> to ignore the uploading error if the package already exists. #2362</li> <li>Use <code>==major.minor.*</code> as default requires python for application projects. #2382</li> <li>We now use the <code>package-type</code> field in the <code>tool.pdm</code> table to differentiate between library and application projects. #2394</li> <li>Add support for {pdm} placeholder in script definitions to call the same PDM entrypoint #2408</li> <li>When exporting requirements, record the environment markers from all parents for each requirement. This allows the exported requirements to work on different platforms and Python versions. #2418</li> <li><code>pdm lock</code> now supports <code>--update-reuse</code> option to keep the pinned versions in the lockfile if possible. #2419</li> <li>Introduce a new lock strategy <code>inherit_metadata</code> to inherit and merge markers from parent requirements. This is enabled by default when creating a new lockfile. #2421</li> <li>New cache methods: <code>symlink_individual</code> for creating a symlink for each individual package file and <code>hardlink</code> for creating hardlinks. #2425</li> <li>Add \"pdm sync\" pre-commit hook #2474</li> <li>New update strategy: <code>reuse-installed</code>. When this strategy is enabled, PDM will try to reuse the versions already installed in the environment, even if the package names are given in the command line following <code>add</code> or <code>update</code>. This strategy is supported by <code>add</code>, <code>update</code> and <code>lock</code> commands. #2479</li> <li>Show subcommand's help info when passing unrecognized arguments. #2480</li> <li>add <code>PDM_CACHE_DIR</code> environment variable to configure cache directory location. #2485</li> </ul>"},{"location":"dev/changelog/#bug-fixes_7","title":"Bug Fixes","text":"<ul> <li>Use the same order of Python interpreters as interactive mode in <code>pdm init -n</code>. #2436</li> <li><code>pdm init</code> now implies <code>--lib</code> if <code>--backend</code> is passed. #2437</li> <li>Fix a bug that link collection ignores package-index-binding. #2442</li> <li>Fix the wrong installation candidates for different architectures on Windows. #2464</li> <li>Fix installing PEP 561 stub-only packages with <code>install.cache_method = \"symlink\"</code>. #2466</li> <li>Fix a <code>KeyError</code> raised by <code>pdm update --unconstrained</code> when the project itself is listed as a dependency. #2483</li> </ul>"},{"location":"dev/changelog/#release-v2104-2023-11-24","title":"Release v2.10.4 (2023-11-24)","text":""},{"location":"dev/changelog/#bug-fixes_8","title":"Bug Fixes","text":"<ul> <li>Do not detect as requirements.txt if the file is a python script. #2416</li> <li>Provide information of the original line when parsing requirement fails. #2417</li> <li>Resolve <code>-r</code> requirements paths relative to the requirement file they are specified in #2422</li> <li>Updating package now overwrites the old files instead of removing before installing. #2423</li> </ul>"},{"location":"dev/changelog/#release-v2103-2023-11-16","title":"Release v2.10.3 (2023-11-16)","text":""},{"location":"dev/changelog/#bug-fixes_9","title":"Bug Fixes","text":"<ul> <li>Create virtualenv for conda base Python. #2409</li> </ul>"},{"location":"dev/changelog/#release-v2102-2023-11-16","title":"Release v2.10.2 (2023-11-16)","text":""},{"location":"dev/changelog/#features-improvements_3","title":"Features &amp; Improvements","text":"<ul> <li>Log the response text when <code>pdm publish</code> fails with HTTP error. #2400</li> </ul>"},{"location":"dev/changelog/#bug-fixes_10","title":"Bug Fixes","text":"<ul> <li>Improve the error message when a specific package can't be found in the lockfile. #2358</li> <li>prevent wrong project name (including space and illegal characters) #2360</li> <li>Fix a bug that PDM cannot detect namespace packages correctly when creating symlinks. The package's <code>__init__.py</code> contains an unusual line. #2378</li> <li>Fix template files created by <code>pdm init</code> being read-only when copied from a read-only PDM installation. #2379</li> <li>Don't reset the build backend when asking for import. #2388</li> <li>Never wrap the output of the <code>export</code> command. #2390</li> <li>Forbid global project in conda base environment, since it may remove conda-managed packages. #2409</li> </ul>"},{"location":"dev/changelog/#release-v2101-2023-11-07","title":"Release v2.10.1 (2023-11-07)","text":""},{"location":"dev/changelog/#bug-fixes_11","title":"Bug Fixes","text":"<ul> <li>Fix a bug preventing ctrl-c from interrupting program execution on 2nd invocation when using \"pdm run\" (Windows only). #2292</li> <li>Fix list index out of range when build error message is empty. #2337</li> <li>Fix find_link sources being exported as <code>--extra--index-url</code> #2342</li> <li>Fix an installation failure when install.cache = true. #2355</li> <li>Fix a resolution issue that extra dependencies are not resolved when the bare dependency has more specific version constraint. #2369</li> </ul>"},{"location":"dev/changelog/#documentation_3","title":"Documentation","text":"<ul> <li>Set up a chatbot powered by LLM on the doc page. #2365</li> </ul>"},{"location":"dev/changelog/#release-v2100-2023-10-26","title":"Release v2.10.0 (2023-10-26)","text":""},{"location":"dev/changelog/#features-improvements_4","title":"Features &amp; Improvements","text":"<ul> <li>Allow binding packages to specific sources with <code>include_packages</code> and <code>exclude_packages</code> config under <code>tool.pdm.source</code> table. #1645</li> <li>Show warnings when a package is rejected by the resolve because of uncovered <code>requires-python</code> range. And provide a way to ignore them per-package. #2304</li> <li>Add <code>-q/--quiet</code> option to suppress some warnings printed to the console. This option is mutually exclusive with <code>-v/--verbose</code>. #2304</li> <li>Introduce a new <code>--strategy/-S</code> option for <code>lock</code> command, to specify one or more strategy flags for resolving dependencies. <code>--static-urls</code> and <code>--no-cross-platform</code> are deprecated at the same time. #2310</li> <li>Add lock option to resolve direct dependencies to the minimal versions available. #2310</li> <li>Report the progress of download and unpacking when installing packages. #2328</li> </ul>"},{"location":"dev/changelog/#bug-fixes_12","title":"Bug Fixes","text":"<ul> <li>Change the venv backend clean function <code>pdm.cli.commands.venv.backend.Backend._ensure_clean</code> to empty the <code>.venv</code> folder instead of deleting it. #2282</li> <li>Fix a bug that dependency groups from Poetry 1.2+ do not migrate properly to PDM. #2285</li> <li>Fix a bug that build requirements are installed into wrong location when using <code>--venv</code> option. #2314</li> <li>Fix a bug that global repository setting results in TypeError . #2330</li> <li>Fix a credentials error when working with two indices on the same host #2333</li> </ul>"},{"location":"dev/changelog/#miscellany","title":"Miscellany","text":"<ul> <li>Officially supports python3.12 now. #2301</li> </ul>"},{"location":"dev/changelog/#release-v293-2023-09-25","title":"Release v2.9.3 (2023-09-25)","text":""},{"location":"dev/changelog/#bug-fixes_13","title":"Bug Fixes","text":"<ul> <li>Revert the changes to the behavior of installing self, introduced in #2162.   Self package won't be installed when <code>--no-default</code> is requested. #2230</li> <li>Reject the candidate if it contains invalid metadata, to avoid a crash in the process of resolution. #2261</li> </ul>"},{"location":"dev/changelog/#documentation_4","title":"Documentation","text":"<ul> <li>Clarify what <code>--no-isolated</code> does. #2071</li> </ul>"},{"location":"dev/changelog/#release-v292-2023-09-12","title":"Release v2.9.2 (2023-09-12)","text":""},{"location":"dev/changelog/#features-improvements_5","title":"Features &amp; Improvements","text":"<ul> <li>Fix an issue that <code>--no-lock</code> option doesn't work as expected. Also support <code>--no-lock</code> option for <code>add</code>, <code>remove</code> and <code>update</code> commands. #2245</li> </ul>"},{"location":"dev/changelog/#bug-fixes_14","title":"Bug Fixes","text":"<ul> <li>Use <code>findpython</code> to find pythons with the spec given by the user. #2225</li> <li>Use UTF-8 to read pyvenv.cfg. #2227</li> <li>On Windows, try looking for the <code>virtualenv</code> <code>python.exe</code> binary under <code>bin/</code>   as well as <code>Scripts/</code> and the <code>virtualenv</code>/<code>conda</code> root. #2236</li> <li>Write relocatable dependency URLs with <code>${PROJECT_ROOT}</code> variable in the lockfile. #2240</li> </ul>"},{"location":"dev/changelog/#release-v291-2023-09-03","title":"Release v2.9.1 (2023-09-03)","text":""},{"location":"dev/changelog/#features-improvements_6","title":"Features &amp; Improvements","text":"<ul> <li>Support convert setup.cfg without existing setup.py. #2222</li> </ul>"},{"location":"dev/changelog/#bug-fixes_15","title":"Bug Fixes","text":"<ul> <li><code>pdm run</code> should only find local file if the command starts with <code>./</code>. #2221</li> </ul>"},{"location":"dev/changelog/#release-v290-2023-08-31","title":"Release v2.9.0 (2023-08-31)","text":""},{"location":"dev/changelog/#features-improvements_7","title":"Features &amp; Improvements","text":"<ul> <li>Add an <code>--overwrite</code> option to <code>pdm init</code> to overwrite existing files(default False). #2163</li> <li>Support passing filter patterns as positional arguments to <code>pdm list</code> command.   Add <code>--tree</code> as an alias and preferred name of <code>--graph</code> option. #2165</li> <li>Switch to truststore by default. #2195</li> <li>Consider packages as installed if the venv includes them from the system-site-packages. #2216</li> <li>Allow <code>pdm run</code> to run a script with the relative or absolute path. #2217</li> </ul>"},{"location":"dev/changelog/#bug-fixes_16","title":"Bug Fixes","text":"<ul> <li>Fix a bug that removing dev dependency uninstalls the project as well. #2150</li> <li>Fix a bug that <code>@ file://</code> dependencies can not be updated. #2169</li> <li>Fix a bug that dependencies requested out of the range of <code>requires-python</code> cause PDM to crash. #2175</li> <li>Fix the compatibility issue with copier 8.0+. #2177</li> <li>Makes <code>comarable_version(\"1.2.3+local1\") == Version(\"1.2.3\")</code>. #2182</li> <li>Default behavior for pdm venv activate when shell detection fails. #2187</li> <li>Handle parsing errors when converting from poetry-style metadata. #2203</li> <li>Don't copy .pyc files from the template directory. #2213</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_1","title":"Removals and Deprecations","text":"<ul> <li>Remove the legacy build backend <code>pdm-pep517</code>. #2167</li> </ul>"},{"location":"dev/changelog/#release-v282-2023-07-31","title":"Release v2.8.2 (2023-07-31)","text":""},{"location":"dev/changelog/#features-improvements_8","title":"Features &amp; Improvements","text":"<ul> <li>Allow setting username and password in URL for publish command #2140</li> </ul>"},{"location":"dev/changelog/#bug-fixes_17","title":"Bug Fixes","text":"<ul> <li>Use UTF-8 encoding when writing <code>sitecustomize.py</code>. #2139</li> </ul>"},{"location":"dev/changelog/#release-v281-2023-07-26","title":"Release v2.8.1 (2023-07-26)","text":""},{"location":"dev/changelog/#features-improvements_9","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>keyring</code>, <code>copier</code>, <code>cookiecutter</code>, <code>template</code>, <code>truststore</code> dependency groups. #2109</li> <li>Ignore wheels for python versions not in range. #2113</li> <li>Read default value from env var <code>PDM_PROJECT</code> for <code>-p/--project</code> option. #2126</li> </ul>"},{"location":"dev/changelog/#bug-fixes_18","title":"Bug Fixes","text":"<ul> <li>Fix the comparison of the candidate keys in the lockfile. #2120</li> <li>Don't update <code>pyproject.toml</code> if both <code>--unconstrained</code> and <code>--dry-run</code> are passed to <code>pdm update</code>. #2125</li> <li>Overwrite the <code>build-system</code> table when importing from other package manager. #2126</li> <li>Skip sources with empty URL when merging sources. #2130</li> <li>Fix the invalid requirement converted from poetry metadata. #2133</li> </ul>"},{"location":"dev/changelog/#dependencies","title":"Dependencies","text":"<ul> <li>Update <code>unearth</code> to 0.10.0 #2113</li> </ul>"},{"location":"dev/changelog/#release-v280-2023-07-15","title":"Release v2.8.0 (2023-07-15)","text":""},{"location":"dev/changelog/#features-improvements_10","title":"Features &amp; Improvements","text":"<ul> <li>Support target python with other architectures. #2078</li> <li>Display the help information when running pdm directly. #2081</li> <li>Allow to change the python providers from the config. Support finding pythons from Rye installation location with the new findpython. #2099</li> <li>Option to save static URLs in the lockfile. By default only filenames are saved. #2101</li> </ul>"},{"location":"dev/changelog/#bug-fixes_19","title":"Bug Fixes","text":"<ul> <li>Fix a bug that egg-info directories are not removed completely, leading to incomplete distribution. #2027</li> <li>Skip distributions with wrong package meta information and duplicate path. #2075</li> <li>Avoid mistakenly passing command-line arguments while testing. #2083</li> <li>Fix a bug that lockfile groups are overwritten when running locking in a preceding step of <code>pdm install</code>. #2086</li> <li>Tolerate and actually ignore the local versions in version specifiers. #2102</li> <li>Fix a bug that shared cache cannot support overlapping namespace packages. #2105</li> </ul>"},{"location":"dev/changelog/#documentation_5","title":"Documentation","text":"<ul> <li>Add notes about using custom venv path. #2096</li> </ul>"},{"location":"dev/changelog/#release-v280a2-2023-06-30","title":"Release v2.8.0a2 (2023-06-30)","text":""},{"location":"dev/changelog/#bug-fixes_20","title":"Bug Fixes","text":"<ul> <li>Fix a bug that dependencies can't be updated when the table is separated by another table. #2056</li> <li>Fix a bug that <code>*_lock</code> hooks are always emitted with dry_run=True in <code>pdm update</code>. #2060</li> <li>Fix a bug that <code>pdm install --plugins</code> can't install self. #2062</li> <li>Fix a cache collision between named requirements and url requirements. #2064</li> </ul>"},{"location":"dev/changelog/#release-v280a1-2023-06-27","title":"Release v2.8.0a1 (2023-06-27)","text":""},{"location":"dev/changelog/#features-improvements_11","title":"Features &amp; Improvements","text":"<ul> <li>Add support for <code>cookiecutter</code> and <code>copier</code> as project generator. #2059</li> </ul>"},{"location":"dev/changelog/#release-v280a0-2023-06-27","title":"Release v2.8.0a0 (2023-06-27)","text":""},{"location":"dev/changelog/#features-improvements_12","title":"Features &amp; Improvements","text":"<ul> <li><code>pdm init</code> now accepts a template argument to initialize project from a built-in or Git template. #2053</li> <li>Replace the <code>DeprecationWarning</code> with <code>FutureWarning</code> for better exposure. #2012</li> <li>Serve <code>install-pdm.py</code> and its checksum file on the docs site. #2026</li> <li>Add new option <code>--edit/-e</code> to <code>pdm config</code> to edit the config file in default editor. #2028</li> <li>Add <code>--project</code> option to <code>pdm venv</code> to support another path as the project root. #2042</li> <li>Add support for using <code>truststore</code> as the SSL backend. This only works on Python 3.10 or newer. #2049</li> </ul>"},{"location":"dev/changelog/#bug-fixes_21","title":"Bug Fixes","text":"<ul> <li>Fix the breaking change by adding the functions back to the old location with deprecation warnings. #2013</li> <li>Fix the duplicate entries in the output of <code>pdm self list</code>. #2018</li> <li>Disable hashes caching for local files. #2019</li> <li>Populate the <code>url</code> field when converting requirements from a Pipfile-style file requirement. #2032</li> <li>Fix a bug that empty source tables in configuration files causes errors when running pdm commands. #2034</li> <li>Fix a resolution conflict caused by requested yanked version also in other transitive dependencies. #2038</li> <li>Fix a bug that binary executables are corrupted when replacing shebangs. #2045</li> <li>Do not normalize the package name when uploading to PyPI. #2057</li> </ul>"},{"location":"dev/changelog/#release-v274-2023-06-13","title":"Release v2.7.4 (2023-06-13)","text":"<p>No significant changes.</p>"},{"location":"dev/changelog/#release-v273-2023-06-13","title":"Release v2.7.3 (2023-06-13)","text":""},{"location":"dev/changelog/#bug-fixes_22","title":"Bug Fixes","text":"<ul> <li>Fix the warning of extras not found due to extra names not normalized. #2006</li> <li>Pop up a warning when the deprecated <code>parser</code> argument is passed to <code>BaseCommand.__init__()</code> method. #2007</li> <li>Fix a bug that merging settings with AoTs causing a failure. #2011</li> </ul>"},{"location":"dev/changelog/#release-v272-2023-06-12","title":"Release v2.7.2 (2023-06-12)","text":""},{"location":"dev/changelog/#features-improvements_13","title":"Features &amp; Improvements","text":"<ul> <li>Add option to expand environment variables when exporting requirements. #1997</li> </ul>"},{"location":"dev/changelog/#bug-fixes_23","title":"Bug Fixes","text":"<ul> <li>Case-insensitive sorting in <code>pdm list</code>. #1973</li> <li>Make a compatible cache reader to read the old cache files. #1981</li> <li>Fix a bug that <code>pdm init -n</code> doesn't respect the <code>--python</code> option. #1984</li> <li>Do not use the deprecated nested argument groups. #1988</li> <li>Fix an error parsing <code>setup.py</code> if it prints something to stdout. #1995</li> <li>Exclude yanked versions when running <code>install-pdm.py</code>. #1996</li> </ul>"},{"location":"dev/changelog/#release-v271-2023-06-06","title":"Release v2.7.1 (2023-06-06)","text":""},{"location":"dev/changelog/#features-improvements_14","title":"Features &amp; Improvements","text":"<ul> <li>Switch HTTP data cache to use a split body setup, where the actual body contents are not written to disk unless changed. Previously, any changed headers would write the whole body to disk again. #1971</li> <li>Show the specific install commands for different installations when checking update. This was removed before. #1972</li> </ul>"},{"location":"dev/changelog/#bug-fixes_24","title":"Bug Fixes","text":"<ul> <li>PDM ignores env vars <code>PDM_PYPI_USERNAME</code> and <code>PDM_PYPI_PASSWORD</code> when there are no defaults in config. #1961</li> <li>Guess the project name from VCS url if it is missing when importing from requirements.txt. #1970</li> <li>Correctly read the config from environment variables. #1977</li> </ul>"},{"location":"dev/changelog/#release-v270-2023-05-29","title":"Release v2.7.0 (2023-05-29)","text":""},{"location":"dev/changelog/#features-improvements_15","title":"Features &amp; Improvements","text":"<ul> <li>When keyring is available, either by importing or by CLI, the credentials of repositories and PyPI indexes will be saved into it. #1908</li> <li>Add support for reading metadata from simple index directly. #1919</li> <li>Add a configuration to specify constant command arguments for every pdm invocation. #1923</li> <li>Add ability to skip SSL verification for publish repositories via <code>repository.custom.verify_ssl</code> config option as well as new command line argument of <code>publish</code> command. #1928</li> <li>Use lazy import to reduce the startup time of the CLI. #1929</li> <li>Add the local plugin scripts to <code>PATH</code> env var. #1944</li> </ul>"},{"location":"dev/changelog/#bug-fixes_25","title":"Bug Fixes","text":"<ul> <li>Don't use install cache when installing build requirements to avoid race condition. #1869</li> <li>Fix a number of <code>ResourceWarning</code>s when running the test suite with warnings enabled. #1915</li> <li>Fix a bug that dev-dependencies group gets updated with the optional dependencies, causing the hash mismatch. #1916</li> <li>Fix format conversion error from Poetry when <code>tool.poetry.build</code> doesn't exist. #1935</li> <li>Add timeout when fetching .gitignore from GitHub. #1937</li> <li>Keep the variables in the URL credentials when exporting. #1939</li> <li>Convert to boolean when setting verify_ssl for custom indexes. #1945</li> <li><code>pdm import</code> clobbers <code>build-system.requires</code> value in <code>pyproject.toml</code>. #1948</li> </ul>"},{"location":"dev/changelog/#documentation_6","title":"Documentation","text":"<ul> <li>Update publish.md to use run instead of runs to match GitHub Actions steps documentation #1936</li> <li>Update advanced.md to use <code>pdm sync</code> instead of <code>pdm install --no-lock</code>. #1947</li> </ul>"},{"location":"dev/changelog/#release-v261-2023-05-10","title":"Release v2.6.1 (2023-05-10)","text":""},{"location":"dev/changelog/#bug-fixes_26","title":"Bug Fixes","text":"<ul> <li>Fix the error when publishing using trusted publisher. #1868</li> <li>Fix a bug that <code>PATH</code> env var isn't set correctly when running under non-isolation mode. #1904</li> </ul>"},{"location":"dev/changelog/#release-v260-2023-05-09","title":"Release v2.6.0 (2023-05-09)","text":""},{"location":"dev/changelog/#features-improvements_16","title":"Features &amp; Improvements","text":"<ul> <li>Install project-level plugins from project config, with <code>tool.pdm.plugins</code> setting. #1461</li> <li>Added a <code>--json</code> flag to both <code>run</code> and <code>info</code> command allowing to dump scripts and infos as JSON. #1854</li> <li>Consider tasks with a name starting by an underscore (<code>_</code>) as internal tasks and hide them from the listing. #1855</li> <li>When running <code>pdm init -n</code>(non-interactive mode), a venv will be created by default. Previously, the selected Python will be used under PEP 582 mode. #1862</li> <li>Support Trusted Publisher. #1868</li> <li>Add an ephemeral wheel cache in process for wheels built from non-static revision sources. #1885</li> <li>Allow self-referencing groups in dev-dependencies. #1890</li> <li>Add an option <code>--no-cross-platform</code> to <code>pdm lock</code> to create a non-cross-platform lockfile. #1898</li> </ul>"},{"location":"dev/changelog/#bug-fixes_27","title":"Bug Fixes","text":"<ul> <li>Fix brackets in <code>--venv</code> option descriptions in zsh completion script. #1847</li> <li>The resolver doesn't take into account of the requirements for both bare <code>package</code> and <code>package[extra]</code>. #1851</li> <li>Default pypi source does not use configured pypi.password, but \"\" instead. #1856 <li>Detect Python interpreters under the root of virtual environments. #1866</li> <li>Fix a race condition when the builder is creating a new build directory. #1869</li> <li>Raise <code>FileNotFoundError</code> if the requirement path is not found. #1875</li> <li>Fix a bug that the self package isn't uninstallable. #1901</li>"},{"location":"dev/changelog/#release-v256-2023-05-07","title":"Release v2.5.6 (2023-05-07)","text":""},{"location":"dev/changelog/#bug-fixes_28","title":"Bug Fixes","text":"<ul> <li>Fix a double reading issue due to cachecontrol not compatible with urllib3 2.0. #1894</li> </ul>"},{"location":"dev/changelog/#release-v255-2023-05-05","title":"Release v2.5.5 (2023-05-05)","text":"<p>No significant changes.</p>"},{"location":"dev/changelog/#release-v254-2023-05-05","title":"Release v2.5.4 (2023-05-05)","text":""},{"location":"dev/changelog/#bug-fixes_29","title":"Bug Fixes","text":"<ul> <li>Pin the urllib3 to <code>&lt;2.0</code> to avoid incompatibility with <code>cachecontrol</code>. #1886</li> </ul>"},{"location":"dev/changelog/#release-v253-2023-04-19","title":"Release v2.5.3 (2023-04-19)","text":""},{"location":"dev/changelog/#bug-fixes_30","title":"Bug Fixes","text":"<ul> <li>Fix the wrong argument validation for update command, where packages given with group option should be allowed. #1836</li> </ul>"},{"location":"dev/changelog/#documentation_7","title":"Documentation","text":"<ul> <li>Update <code>markdown-exec</code> to <code>1.5.0</code> for rendering TOC in CLI reference page. #1836</li> <li>Remove advertizing of PEP-582 from the feature highlights. Improve the anchor links for CLI reference. #1840</li> </ul>"},{"location":"dev/changelog/#release-v252-2023-04-10","title":"Release v2.5.2 (2023-04-10)","text":""},{"location":"dev/changelog/#bug-fixes_31","title":"Bug Fixes","text":"<ul> <li>Regression(#1710): Don't crash when trying to update the shebang in a binary script #1827</li> <li>Rename the env var <code>PDM_USE_VENV</code> as <code>PDM_IN_VENV</code> for <code>--venv</code> flag as it mistakenly override another existing env var. #1829</li> </ul>"},{"location":"dev/changelog/#release-v251-2023-04-09","title":"Release v2.5.1 (2023-04-09)","text":""},{"location":"dev/changelog/#bug-fixes_32","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>pdm --pep582</code> raises an argument error. #1823</li> </ul>"},{"location":"dev/changelog/#release-v250-2023-04-09","title":"Release v2.5.0 (2023-04-09)","text":""},{"location":"dev/changelog/#features-improvements_17","title":"Features &amp; Improvements","text":"<ul> <li>When <code>resolution.respect-source-order</code> is enabled, sources are lazily evaluated. This means that if a match is found on the first source, the remaining sources will not be requested. #1509</li> <li>New option <code>--venv &lt;venv&gt;</code> to run a command in the virtual environment with the given name. #1705</li> <li>Allow to prefer binary distributions when locking and installing packages, via <code>PDM_PREFER_BINARY</code> environment variable. #1817</li> </ul>"},{"location":"dev/changelog/#bug-fixes_33","title":"Bug Fixes","text":"<ul> <li>Do not validate selected groups against the locked grouped when running <code>pdm lock</code>. #1796</li> <li>Avoid duplicate .pdm-python in .gitignore. #1800</li> <li>Fix a backwards compatibility issue by adding back the <code>environment.is_global</code> property. #1814</li> <li>Fix a resolution conflict when a relative path requirement resolves to the same path as another file requirement with absolute path. #1822</li> <li>Fix an error when running <code>pdm init -p &lt;dir&gt;</code> if the target directory is not created yet. #1822</li> </ul>"},{"location":"dev/changelog/#release-v250b0-2023-03-29","title":"Release v2.5.0b0 (2023-03-29)","text":""},{"location":"dev/changelog/#breaking-changes","title":"Breaking Changes","text":"<ul> <li>Switch the default build backend to <code>pdm-backend</code>. #1684</li> <li>Only lock selected groups into the lockfile. Modify other commands to honor the groups included in the lockfile. #1704</li> <li>Move the project python path to its own file, and rename the project config file as <code>pdm.toml</code> which can be committed to the VCS. #1742</li> <li>Refactor the environment package. <code>Environment</code> is renamed to <code>PythonLocalEnvironment</code> and <code>GlobalEnvironment</code> is renamed to <code>PythonEnvironment</code>. Move <code>pdm.models.environment</code> module to <code>pdm.environments</code> package. #1791</li> </ul>"},{"location":"dev/changelog/#features-improvements_18","title":"Features &amp; Improvements","text":"<ul> <li>Add option to fail on the first install error. #1614</li> <li>Upgrade <code>unearth</code> to 0.8 to allow calling keyring from CLI. #1653</li> <li>Merge the index parameters from different configuration files. #1667</li> <li>Add new options to <code>venv</code> command to show the path or the python interpreter for a managed venv. #1680</li> <li>Write the groups of resolved dependencies to the metadata table in lockfile. #1692</li> <li>Introduce <code>--lib</code> option to <code>init</code> command to create a library project without prompting. #1708</li> <li>New command: <code>pdm fix</code> to migrate to the new PDM features. Add a hint when invoking PDM commands. #1743</li> <li>Include <code>.pdm-python</code> in project root <code>.gitignore</code> when running <code>pdm init</code>. #1749</li> <li>Allow to ignore the activated venv with <code>PDM_IGNORE_ACTIVE_VENV</code> env var. #1782</li> <li>Add a signal <code>pre_invoke</code> to emit before any command is invoked. #1792</li> </ul>"},{"location":"dev/changelog/#bug-fixes_34","title":"Bug Fixes","text":"<ul> <li>Fix a bug that install warning prints to terminal under non-verbose mode. #1635</li> <li>Fix the random failure of <code>pdm export</code> due to non-deterministic order of group iteration. #1786</li> <li>Show the actual version when running <code>pdm show --version</code> #1788</li> </ul>"},{"location":"dev/changelog/#documentation_8","title":"Documentation","text":"<ul> <li>Restructure the documentation. #1687</li> </ul>"},{"location":"dev/changelog/#dependencies_1","title":"Dependencies","text":"<ul> <li>Update <code>installer</code> to <code>0.7.0</code> and emit a warning if the RECORD validation fails. #1784</li> </ul>"},{"location":"dev/changelog/#release-v249-2023-03-16","title":"Release v2.4.9 (2023-03-16)","text":""},{"location":"dev/changelog/#bug-fixes_35","title":"Bug Fixes","text":"<ul> <li>Fix a bug of synchronization of not considering the revision of VCS requirement in comparison. #1762</li> <li>Improve the error message when parsing an invalid requirement string. #1765</li> <li>Fix a bug that <code>pdm export</code> output doesn't include the extras of the dependencies. #1767</li> </ul>"},{"location":"dev/changelog/#release-v248-2023-03-09","title":"Release v2.4.8 (2023-03-09)","text":""},{"location":"dev/changelog/#bug-fixes_36","title":"Bug Fixes","text":"<ul> <li>Fix the resolution order to prefer the packages causing the conflict.   This can make the resolution reach a solution faster. #1752</li> <li>Fix a bug that embedded credentials in URL are not respected for the default source. #1757</li> </ul>"},{"location":"dev/changelog/#release-v247-2023-03-02","title":"Release v2.4.7 (2023-03-02)","text":""},{"location":"dev/changelog/#bug-fixes_37","title":"Bug Fixes","text":"<ul> <li>Abort if lockfile isn't generated when executing <code>pdm export</code>. #1730</li> <li>Ignore <code>venv.prompt</code> configuration when using <code>conda</code> as the backend. #1734</li> <li>Fix a bug of finding local packages in the parent folder when it exists in the current folder. #1736</li> <li>Ensure UTF-8 encoding when generating README.md. #1739</li> <li>Fix a bug of show command not showing metadata of the current project. #1740</li> <li>Replace <code>.</code> with <code>-</code> when normalizing package name. #1745</li> </ul>"},{"location":"dev/changelog/#documentation_9","title":"Documentation","text":"<ul> <li>Support using <code>pdm venv activate</code> without specifying <code>env_name</code> to activate in project venv created by conda #1735</li> </ul>"},{"location":"dev/changelog/#release-v246-2023-02-20","title":"Release v2.4.6 (2023-02-20)","text":""},{"location":"dev/changelog/#bug-fixes_38","title":"Bug Fixes","text":"<ul> <li>Fix a resolution failure when the project has cascading relative path dependencies. #1702</li> <li>Don't crash when trying to update the shebang in a binary script. #1709</li> <li>Handle the legacy specifiers that is unable to parse with packaging&gt;22.0. #1719</li> <li>Fix the setup.py parser to ignore the expressions unable to parse as a string. This is safe for initializing a requirement. #1720</li> <li>Fix a bug converting from flit metadata when the source file can't be found. #1726</li> </ul>"},{"location":"dev/changelog/#documentation_10","title":"Documentation","text":"<ul> <li>Add config example for Emacs using eglot + pyright #1721</li> </ul>"},{"location":"dev/changelog/#miscellany_1","title":"Miscellany","text":"<ul> <li>Use <code>ruff</code> as the linter. #1715</li> <li>Document installation via <code>asdf</code>. #1725</li> </ul>"},{"location":"dev/changelog/#release-v245-2023-02-10","title":"Release v2.4.5 (2023-02-10)","text":""},{"location":"dev/changelog/#bug-fixes_39","title":"Bug Fixes","text":"<ul> <li>Fix a bug that built wheels are prioritized over source distributions with higher version number. #1698</li> </ul>"},{"location":"dev/changelog/#release-v244-2023-02-10","title":"Release v2.4.4 (2023-02-10)","text":""},{"location":"dev/changelog/#features-improvements_19","title":"Features &amp; Improvements","text":"<ul> <li>Add more intuitive error message when the <code>requires-python</code> doesn't work for all dependencies. #1690</li> </ul>"},{"location":"dev/changelog/#bug-fixes_40","title":"Bug Fixes","text":"<ul> <li>Prefer built distributions when finding packages for metadata extraction. #1535</li> </ul>"},{"location":"dev/changelog/#release-v243-2023-02-06","title":"Release v2.4.3 (2023-02-06)","text":""},{"location":"dev/changelog/#features-improvements_20","title":"Features &amp; Improvements","text":"<ul> <li>Allow creating venv in project forcely if it already exists. #1666</li> <li>Always ignore remembered selection in pdm init. #1672</li> </ul>"},{"location":"dev/changelog/#bug-fixes_41","title":"Bug Fixes","text":"<ul> <li>Fix the fallback build backend to <code>pdm-pep517</code> instead of <code>setuptools</code>. #1658</li> <li>Eliminate the deprecation warnings from <code>importlib.resources</code>. #1660</li> <li>Don't crash when failed to get the latest version of PDM for checking update. #1663</li> <li>Fix the priorities of importable formats to make sure the correct format is used. #1669</li> <li>Import editable requirements into dev dependencies. #1674</li> </ul>"},{"location":"dev/changelog/#release-v242-2023-01-31","title":"Release v2.4.2 (2023-01-31)","text":""},{"location":"dev/changelog/#bug-fixes_42","title":"Bug Fixes","text":"<ul> <li>Skip some tests on packaging &lt; 22. #1649</li> <li>Fix a bug that sources from the project config are not loaded. #1651</li> <li>Set VIRTUAL_ENV in <code>pdm run</code>. #1652</li> </ul>"},{"location":"dev/changelog/#release-v241-2023-01-28","title":"Release v2.4.1 (2023-01-28)","text":""},{"location":"dev/changelog/#features-improvements_21","title":"Features &amp; Improvements","text":"<ul> <li>Add proper display for the extra pypi sources in <code>pdm config</code>. #1622</li> <li>Support running python scripts without prefixing with <code>python</code>. #1626</li> </ul>"},{"location":"dev/changelog/#bug-fixes_43","title":"Bug Fixes","text":"<ul> <li>Ignore the python requirement for overriden packages. #1575</li> <li>Fix the wildcards in requirement specifiers to make it pass the new parser of <code>packaging&gt;=22</code>. #1619</li> <li>Add the missing <code>subdirectory</code> attribute to the lockfile entry. #1630</li> <li>Fix a bug that VCS locks don't update when the rev part changes. #1640</li> <li>Redirect the spinner output to stderr. #1646</li> <li>Ensure the destination directory exists before building the packages. #1647</li> </ul>"},{"location":"dev/changelog/#release-v240-2023-01-12","title":"Release v2.4.0 (2023-01-12)","text":""},{"location":"dev/changelog/#features-improvements_22","title":"Features &amp; Improvements","text":"<ul> <li>Support multiple PyPI indexes in the configuration. They will be tried after the sources in <code>pyproject.toml</code>. #1310</li> <li>Accept yanked versions when the requirement version is pinned. #1575</li> <li>Expose PDM fixtures as a <code>pytest</code> plugin <code>pdm.pytest</code> for plugin developers. #1594</li> <li>Show message in the status when fetching package hashes.   Fetch hashes from the JSON API response as well. #1609</li> <li>Mark <code>pdm.lock</code> with an <code>@generated</code> comment. #1611</li> </ul>"},{"location":"dev/changelog/#bug-fixes_44","title":"Bug Fixes","text":"<ul> <li>Exclude site-packages for symlinks of the python interpreter as well. #1598</li> <li>Fix a bug that error output can't be decoded correctly on Windows. #1602</li> </ul>"},{"location":"dev/changelog/#release-v234-2022-12-27","title":"Release v2.3.4 (2022-12-27)","text":""},{"location":"dev/changelog/#features-improvements_23","title":"Features &amp; Improvements","text":"<ul> <li>Detect PDM inside a zipapp and disable some functions. #1578</li> </ul>"},{"location":"dev/changelog/#bug-fixes_45","title":"Bug Fixes","text":"<ul> <li>Don't write <code>sitecustomize</code> to the home directory if it exists in the filesystem(not packed in a zipapp). #1572</li> <li>Fix a bug that a directory is incorrectly marked as to be deleted when it contains symlinks. #1580</li> </ul>"},{"location":"dev/changelog/#release-v233-2022-12-15","title":"Release v2.3.3 (2022-12-15)","text":""},{"location":"dev/changelog/#bug-fixes_46","title":"Bug Fixes","text":"<ul> <li>Allow relative paths in <code>build-system.requires</code>, since <code>build</code> and <code>hatch</code> both support it. Be aware it is not allowed in the standard. #1560</li> <li>Strip the local part when building a specifier for comparison with the package version. This is not permitted by PEP 508 as implemented by <code>packaging 22.0</code>. #1562</li> <li>Update the version for check_update after self update #1563</li> <li>Replace the <code>__file__</code> usages with <code>importlib.resources</code>, to make PDM usable in a zipapp. #1567</li> <li>Fix the matching problem of packages in the lockfile. #1569</li> </ul>"},{"location":"dev/changelog/#dependencies_2","title":"Dependencies","text":"<ul> <li>Exclude <code>package==22.0</code> from the dependencies to avoid some breakages to the end users. #1568</li> </ul>"},{"location":"dev/changelog/#release-v232-2022-12-08","title":"Release v2.3.2 (2022-12-08)","text":""},{"location":"dev/changelog/#bug-fixes_47","title":"Bug Fixes","text":"<ul> <li>Fix an installation failure when the RECORD file contains commas in the file path. #1010</li> <li>Fallback to <code>pdm.pep517</code> as the metadata transformer for unknown custom build backends. #1546</li> <li>Fix a bug that Ctrl + C kills the python interactive session instead of clearing the current line. #1547</li> <li>Fix a bug with egg segment for local dependency #1552</li> </ul>"},{"location":"dev/changelog/#dependencies_3","title":"Dependencies","text":"<ul> <li>Update <code>installer</code> to <code>0.6.0</code>. #1550</li> <li>Update minimum version of <code>unearth</code> to <code>0.6.3</code> and test against <code>packaging==22.0</code>. #1555</li> </ul>"},{"location":"dev/changelog/#release-v231-2022-12-05","title":"Release v2.3.1 (2022-12-05)","text":""},{"location":"dev/changelog/#bug-fixes_48","title":"Bug Fixes","text":"<ul> <li>Fix a resolution loop issue when the current project depends on itself and it uses the dynamic version from SCM. #1541</li> <li>Don't give duplicate results when specifying a relative path for <code>pdm use</code>. #1542</li> </ul>"},{"location":"dev/changelog/#release-v230-2022-12-02","title":"Release v2.3.0 (2022-12-02)","text":""},{"location":"dev/changelog/#features-improvements_24","title":"Features &amp; Improvements","text":"<ul> <li>Beautify the error message of build errors. Default to showing the last 10 lines of the build output. #1491</li> <li>Rename the <code>tool.pdm.overrides</code> table to <code>tool.pdm.resolution.overrides</code>. The old name is deprecated at the same time. #1503</li> <li>Add backend selection and <code>--backend</code> option to <code>pdm init</code> command, users can choose a favorite backend from <code>setuptools</code>, <code>flit</code>, <code>hatchling</code> and <code>pdm-pep517</code>(default), since they all support PEP 621 standards. #1504</li> <li>Allows specifying the insertion position of user provided arguments in scripts with the <code>{args[:default]}</code> placeholder. #1507</li> </ul>"},{"location":"dev/changelog/#bug-fixes_49","title":"Bug Fixes","text":"<ul> <li>The local package is now treated specially during installation and locking. This means it will no longer be included in the lockfile, and should never be installed twice even when using nested extras. This will ensure the lockdown stays relevant when the version changes. #1481</li> <li>Fix the version diff algorithm of installed packages to consider local versions as compatible. #1497</li> <li>Fix the confusing message when detecting a Python interpreter under <code>python.use_venv=False</code> #1508</li> <li>Fix the test failure with the latest <code>findpython</code> installed. #1516</li> <li>Fix the module missing error of pywin32 in a virtualenv with <code>install.cache</code> set to <code>true</code> and caching method is <code>pth</code>. #863</li> </ul>"},{"location":"dev/changelog/#dependencies_4","title":"Dependencies","text":"<ul> <li>Drop the dependency <code>pdm-pep517</code>. #1504</li> <li>Replace <code>pep517</code> with <code>pyproject-hooks</code> because of the rename. #1528</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_2","title":"Removals and Deprecations","text":"<ul> <li>Remove the support for exporting the project file to a <code>setup.py</code> format, users are encouraged to migrate to the PEP 621 metadata. #1504</li> </ul>"},{"location":"dev/changelog/#release-v221-2022-11-03","title":"Release v2.2.1 (2022-11-03)","text":""},{"location":"dev/changelog/#features-improvements_25","title":"Features &amp; Improvements","text":"<ul> <li>Make <code>sitecustomize.py</code> respect the <code>PDM_PROJECT_MAX_DEPTH</code> environment variable #1471</li> </ul>"},{"location":"dev/changelog/#bug-fixes_50","title":"Bug Fixes","text":"<ul> <li>Fix the comparison of <code>python_version</code> in the environment marker. When the version contains only one digit, the result was incorrect. #1484</li> </ul>"},{"location":"dev/changelog/#release-v220-2022-10-31","title":"Release v2.2.0 (2022-10-31)","text":""},{"location":"dev/changelog/#features-improvements_26","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>venv.prompt</code> configuration to allow customizing prompt when a virtualenv is activated #1332</li> <li>Allow the use of custom CA certificates per publish repository using <code>ca_certs</code> or from the command line via <code>pdm publish --ca-certs &lt;path&gt; ...</code>. #1392</li> <li>Rename the <code>plugin</code> command to <code>self</code>, and it can not only manage plugins but also all dependencies. Add a subcommand <code>self update</code> to update PDM itself. #1406</li> <li>Allow <code>pdm init</code> to receive a Python path or version via <code>--python</code> option. #1412</li> <li>Add a default value for <code>requires-python</code> when importing from other formats. #1426</li> <li>Use <code>pdm</code> instead of <code>pip</code> to resolve and install build requirements. So that PDM configurations can control the process. #1429</li> <li>Customizable color theme via <code>pdm config</code> command. #1450</li> <li>A new <code>pdm lock --check</code> flag to validate whether the lock is up to date. #1459</li> <li>Add both option and config item to ship <code>pip</code> when creating a new venv. #1463</li> <li>Issue warning and skip the requirement if it has the same name as the current project. #1466</li> <li>Enhance the <code>pdm list</code> command with new formats: <code>--csv,--markdown</code> and add options <code>--fields,--sort</code> to control the output contents. Users can also include <code>licenses</code> in the <code>--fields</code> option to display the package licenses. #1469</li> <li>A new pre-commit hook to run <code>pdm lock --check</code> in pre-commit. #1471</li> </ul>"},{"location":"dev/changelog/#bug-fixes_51","title":"Bug Fixes","text":"<ul> <li>Fix the issue that relative paths don't work well with <code>--project</code> argument. #1220</li> <li>It is now possible to refer to a package from outside the project with relative paths in dependencies. #1381</li> <li>Ensure <code>pypi.[ca,client]_cert[s]</code> config items are passed to distribution builder install steps to allow for custom PyPI index sources with self signed certificates. #1396</li> <li>Fix a crash issue when depending on editable packages with extras. #1401</li> <li>Do not save the python path when using non-interactive mode in <code>pdm init</code>. #1410</li> <li>Fix the matching of <code>python*</code> command in <code>pdm run</code>. #1414</li> <li>Show the Python path, instead of the real executable, in the Python selection menu. #1418</li> <li>Fix the HTTP client of package publishment to prompt for password and read PDM configurations correctly. #1430</li> <li>Ignore the unknown fields when constructing a requirement object. #1445</li> <li>Fix a bug of unrelated candidates being fetched if the requirement is matching wildcard versions(e.g. <code>==1.*</code>). #1465</li> <li>Use <code>importlib-metadata</code> from PyPI for Python &lt; 3.10. #1467</li> </ul>"},{"location":"dev/changelog/#documentation_11","title":"Documentation","text":"<ul> <li>Clarify the difference between a library and an application. Update the guide of multi-stage docker build. #1371</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_3","title":"Removals and Deprecations","text":"<ul> <li>Remove all top-level imports, users should import from the submodules instead. #1404</li> <li>Remove the usages of old config names deprecated since 2.0. #1422</li> <li>Remove the deprecated color functions, use rich's console markup instead. #1452</li> </ul>"},{"location":"dev/changelog/#release-v215-2022-10-05","title":"Release v2.1.5 (2022-10-05)","text":""},{"location":"dev/changelog/#bug-fixes_52","title":"Bug Fixes","text":"<ul> <li>Ensure <code>pypi.[ca,client]_cert[s]</code> config items are passed to distribution builder install steps to allow for custom PyPI index sources with self signed certificates. #1396</li> <li>Fix a crash issue when depending on editable packages with extras. #1401</li> <li>Do not save the python path when using non-interactive mode in <code>pdm init</code>. #1410</li> <li>Restrict importlib-metadata (&lt;5.0.0) for Python &lt;3.8 #1411</li> </ul>"},{"location":"dev/changelog/#release-v214-2022-09-17","title":"Release v2.1.4 (2022-09-17)","text":""},{"location":"dev/changelog/#bug-fixes_53","title":"Bug Fixes","text":"<ul> <li>Fix a lock failure when depending on self with URL requirements. #1347</li> <li>Ensure list to concatenate args for composite scripts. #1359</li> <li>Fix an error in <code>pdm lock --refresh</code> if some packages has URLs. #1361</li> <li>Fix unnecessary package downloads and VCS clones for certain commands. #1370</li> <li>Fix a conversion error when converting a list of conditional dependencies from a Poetry format. #1383</li> </ul>"},{"location":"dev/changelog/#documentation_12","title":"Documentation","text":"<ul> <li>Adds a section to the docs on how to correctly work with PDM and version control systems. #1364</li> </ul>"},{"location":"dev/changelog/#release-v213-2022-08-30","title":"Release v2.1.3 (2022-08-30)","text":""},{"location":"dev/changelog/#features-improvements_27","title":"Features &amp; Improvements","text":"<ul> <li>When adding a package to (or removing from) a group, enhance the formatting of the group name in the printed message. #1329</li> </ul>"},{"location":"dev/changelog/#bug-fixes_54","title":"Bug Fixes","text":"<ul> <li>Fix a bug of missing hashes for packages with <code>file://</code> links the first time they are added. #1325</li> <li>Ignore invalid values of <code>data-requires-python</code> when parsing package links. #1334</li> <li>Leave an incomplete project metadata if PDM fails to parse the project files, but emit a warning. #1337</li> <li>Fix the bug that <code>editables</code> package isn't installed for self package. #1344</li> <li>Fix a decoding error for non-ASCII characters in package description when publishing it. #1345</li> </ul>"},{"location":"dev/changelog/#documentation_13","title":"Documentation","text":"<ul> <li>Clarify documentation explaining <code>setup-script</code>, <code>run-setuptools</code>, and <code>is-purelib</code>. #1327</li> </ul>"},{"location":"dev/changelog/#release-v212-2022-08-15","title":"Release v2.1.2 (2022-08-15)","text":""},{"location":"dev/changelog/#bug-fixes_55","title":"Bug Fixes","text":"<ul> <li>Fix a bug that dependencies from different versions of the same package override each other. #1307</li> <li>Forward SIGTERM to child processes in <code>pdm run</code>. #1312</li> <li>Fix errors when running on FIPS 140-2 enabled systems using Python 3.9 and newer. #1313</li> <li>Fix the build failure when the subprocess outputs with non-UTF8 characters. #1319</li> <li>Delay the trigger of <code>post_lock</code> for <code>add</code> and <code>update</code> operations, to ensure the <code>pyproject.toml</code> is updated before the hook is run. #1320</li> </ul>"},{"location":"dev/changelog/#release-v211-2022-08-05","title":"Release v2.1.1 (2022-08-05)","text":""},{"location":"dev/changelog/#features-improvements_28","title":"Features &amp; Improvements","text":"<ul> <li>Add a env_file.override option that allows the user to specify that   the env_file should override any existing environment variables. This   is not the default as the environment the code runs it should take   precedence. #1299</li> </ul>"},{"location":"dev/changelog/#bug-fixes_56","title":"Bug Fixes","text":"<ul> <li>Fix a bug that unnamed requirements can't override the old ones in either <code>add</code> or <code>update</code> command. #1287</li> <li>Support mutual TLS to private repositories via pypi.client_cert and pypi.client_key config options. #1290</li> <li>Set a minimum version for the <code>packaging</code> dependency to ensure that <code>packaging.utils.parse_wheel_filename</code> is available. #1293</li> <li>Fix a bug that checking for PDM update creates a venv. #1301</li> <li>Prefer compatible packages when fetching metadata. #1302</li> </ul>"},{"location":"dev/changelog/#release-v210-2022-07-29","title":"Release v2.1.0 (2022-07-29)","text":""},{"location":"dev/changelog/#features-improvements_29","title":"Features &amp; Improvements","text":"<ul> <li>Allow the use of custom CA certificates using the <code>pypi.ca_certs</code> config entry. #1240</li> <li>Add <code>pdm export</code> to available pre-commit hooks. #1279</li> </ul>"},{"location":"dev/changelog/#bug-fixes_57","title":"Bug Fixes","text":"<ul> <li>Skip incompatible requirements when installing build dependencies. #1264</li> <li>Fix a crash when pdm tries to publish a package with non-ASCII characters in the metadata. #1270</li> <li>Try to read the lock file even if the lock version is incompatible. #1273</li> <li>For packages that are only available as source distribution, the <code>summary</code> field in <code>pdm.lock</code> contains the <code>description</code> from the package's <code>pyproject.toml</code>. #1274</li> <li>Do not crash when calling <code>pdm show</code> for a package that is only available as source distribution. #1276</li> <li>Fix a bug that completion scripts are interpreted as rich markups. #1283</li> </ul>"},{"location":"dev/changelog/#dependencies_5","title":"Dependencies","text":"<ul> <li>Remove the dependency of <code>pip</code>. #1268</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_4","title":"Removals and Deprecations","text":"<ul> <li>Deprecate the top-level imports from <code>pdm</code> module, it will be removed in the future. #1282</li> </ul>"},{"location":"dev/changelog/#release-v203-2022-07-22","title":"Release v2.0.3 (2022-07-22)","text":""},{"location":"dev/changelog/#bug-fixes_58","title":"Bug Fixes","text":"<ul> <li>Support Conda environments when detecting the project environment. #1253</li> <li>Fix the interpreter resolution to first try <code>python</code> executable in the <code>PATH</code>. #1255</li> <li>Stabilize sorting of URLs in <code>metadata.files</code> in <code>pdm.lock</code>. #1256</li> <li>Don't expand credentials in the file URLs in the <code>[metada.files]</code> table of the lock file. #1259</li> </ul>"},{"location":"dev/changelog/#release-v202-2022-07-20","title":"Release v2.0.2 (2022-07-20)","text":""},{"location":"dev/changelog/#features-improvements_30","title":"Features &amp; Improvements","text":"<ul> <li><code>env_file</code> variables no longer override existing environment variables. #1235</li> <li>Support referencing other optional groups in optional-dependencies with <code>&lt;this_package_name&gt;[group1, group2]</code> #1241</li> </ul>"},{"location":"dev/changelog/#bug-fixes_59","title":"Bug Fixes","text":"<ul> <li>Respect <code>requires-python</code> when creating the default venv. #1237</li> </ul>"},{"location":"dev/changelog/#release-v201-2022-07-17","title":"Release v2.0.1 (2022-07-17)","text":""},{"location":"dev/changelog/#bug-fixes_60","title":"Bug Fixes","text":"<ul> <li>Write lockfile before calling 'post_lock' hook #1224</li> <li>Suppress errors when cache dir isn't accessible. #1226</li> <li>Don't save python path for venv commands. #1230</li> </ul>"},{"location":"dev/changelog/#release-v200-2022-07-15","title":"Release v2.0.0 (2022-07-15)","text":""},{"location":"dev/changelog/#bug-fixes_61","title":"Bug Fixes","text":"<ul> <li>Fix a bug that the running env overrides the PEP 582 <code>PYTHONPATH</code>. #1211</li> <li>Add <code>pwsh</code> as an alias of <code>powershell</code> for shell completion. #1216</li> <li>Fixed a bug with <code>zsh</code> completion regarding <code>--pep582</code> flag. #1218</li> <li>Fix a bug of requirement checking under non-isolated mode. #1219</li> <li>Fix a bug when removing packages, TOML document might become invalid. #1221</li> </ul>"},{"location":"dev/changelog/#release-v200b2-2022-07-08","title":"Release v2.0.0b2 (2022-07-08)","text":""},{"location":"dev/changelog/#breaking-changes_1","title":"Breaking Changes","text":"<ul> <li>Store file URLs instead of filenames in the lock file, bump lock version to <code>4.0</code>. #1203</li> </ul>"},{"location":"dev/changelog/#features-improvements_31","title":"Features &amp; Improvements","text":"<ul> <li>Read site-wide configuration, which serves as the lowest-priority layer.   This layer will be read-only in the CLI. #1200</li> <li>Get package links from the urls stored in the lock file. #1204</li> </ul>"},{"location":"dev/changelog/#bug-fixes_62","title":"Bug Fixes","text":"<ul> <li>Fix a bug that the host pip(installed with pdm) may not be compatible with the project python. #1196</li> <li>Update <code>unearth</code> to fix a bug that install links with weak hashes are skipped. This often happens on self-hosted PyPI servers. #1202</li> </ul>"},{"location":"dev/changelog/#release-v200b1-2022-07-02","title":"Release v2.0.0b1 (2022-07-02)","text":""},{"location":"dev/changelog/#features-improvements_32","title":"Features &amp; Improvements","text":"<ul> <li>Integrate <code>pdm venv</code> commands into the main program. Make PEP 582 an opt-in feature. #1162</li> <li>Add config <code>global_project.fallback_verbose</code> defaulting to <code>True</code>. When set to <code>False</code> disables message <code>Project is not found, fallback to the global project</code> #1188</li> <li>Add <code>--only-keep</code> option to <code>pdm sync</code> to keep only selected packages. Originally requested at #398. #1191</li> </ul>"},{"location":"dev/changelog/#bug-fixes_63","title":"Bug Fixes","text":"<ul> <li>Fix a bug that requirement extras and underlying are resolved to the different version #1173</li> <li>Update <code>unearth</code> to <code>0.4.1</code> to skip the wheels with invalid version parts. #1178</li> <li>Fix reading <code>PDM_RESOLVE_MAX_ROUNDS</code> environment variable (was spelled <code>\u2026ROUDNS</code> before). #1180</li> <li>Deduplicate the list of found Python versions. #1182</li> <li>Use the normal stream handler for logging, to fix some display issues under non-tty environments. #1184</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_5","title":"Removals and Deprecations","text":"<ul> <li>Remove the useless <code>--no-clean</code> option from <code>pdm sync</code> command. #1191</li> </ul>"},{"location":"dev/changelog/#release-v200a1-2022-06-29","title":"Release v2.0.0a1 (2022-06-29)","text":""},{"location":"dev/changelog/#breaking-changes_2","title":"Breaking Changes","text":"<ul> <li>Editable dependencies in the <code>[project]</code> table is not allowed, according to PEP 621. They are however still allowed in the <code>[tool.pdm.dev-dependencies]</code> table. PDM will emit a warning when it finds editable dependencies in the <code>[project]</code> table, or will abort when you try to add them into the <code>[project]</code> table via CLI. #1083</li> <li>Now the paths to the global configurations and global project are calculated according to platform standards. #1161</li> </ul>"},{"location":"dev/changelog/#features-improvements_33","title":"Features &amp; Improvements","text":"<ul> <li>Add support for importing from a <code>setup.py</code> project. #1062</li> <li>Switch the UI backend to <code>rich</code>. #1091</li> <li>Improved the terminal UI and logging. Disable live progress under verbose mode. The logger levels can be controlled by the <code>-v</code> option. #1096</li> <li>Use <code>unearth</code> to replace <code>pip</code>'s <code>PackageFinder</code> and related data models. PDM no longer relies on <code>pip</code> internals, which are unstable across updates. #1096</li> <li>Lazily load the candidates returned by <code>find_matches()</code> to speed up the resolution. #1098</li> <li>Add a new command <code>publish</code> to PDM since it is required for so many people and it will make the workflow easier. #1107</li> <li>Add a <code>composite</code> script kind allowing to run multiple defined scripts in a single command as well as reusing scripts but overriding <code>env</code> or <code>env_file</code>. #1117</li> <li>Add a new execution option <code>--skip</code> to opt-out some scripts and hooks from any execution (both scripts and PDM commands). #1127</li> <li>Add the <code>pre/post_publish</code>, <code>pre/post_run</code> and <code>pre/post_script</code> hooks as well as an extensive lifecycle and hooks documentation. #1147</li> <li>Shorter scripts listing, especially for multilines and composite scripts. #1151</li> <li>Build configurations have been moved to <code>[tool.pdm.build]</code>, according to <code>pdm-pep517 1.0.0</code>. At the same time, warnings will be shown against old usages. #1153</li> <li>Improve the lock speed by parallelizing the hash fetching. #1154</li> <li>Retrieve the candidate metadata by parsing the <code>pyproject.toml</code> rather than building it. #1156</li> <li>Update the format converters to support the new <code>[tool.pdm.build]</code> table. #1157</li> <li>Scripts are now available as root command if they don't conflict with any builtin or plugin-contributed command. #1159</li> <li>Add a <code>post_use</code> hook triggered after successfully switching Python version. #1163</li> <li>Add project configuration <code>respect-source-order</code> under <code>[tool.pdm.resolution]</code> to respect the source order in the <code>pyproject.toml</code> file. Packages will be returned by source earlier in the order or later ones if not found. #593</li> </ul>"},{"location":"dev/changelog/#bug-fixes_64","title":"Bug Fixes","text":"<ul> <li>Fix a bug that candidates with local part in the version can't be found and installed correctly. #1093</li> </ul>"},{"location":"dev/changelog/#dependencies_6","title":"Dependencies","text":"<ul> <li>Prefer <code>tomllib</code> on Python 3.11 #1072</li> <li>Drop the vendored libraries <code>click</code>, <code>halo</code>, <code>colorama</code> and <code>log_symbols</code>. PDM has no vendors now. #1091</li> <li>Update dependency version <code>pdm-pep517</code> to <code>1.0.0</code>. #1153</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_6","title":"Removals and Deprecations","text":"<ul> <li>PDM legacy metadata format(from <code>pdm 0.x</code>) is no longer supported. #1157</li> </ul>"},{"location":"dev/changelog/#miscellany_2","title":"Miscellany","text":"<ul> <li>Provide a <code>tox.ini</code> file for easier local testing against all Python versions. #1160</li> </ul>"},{"location":"dev/changelog/#release-v1154-2022-06-28","title":"Release v1.15.4 (2022-06-28)","text":""},{"location":"dev/changelog/#bug-fixes_65","title":"Bug Fixes","text":"<ul> <li>Revert #1106: Do not use <code>venv</code> scheme for <code>prefix</code> kind install scheme. #1158</li> <li>Fix a bug when updating a package with extra requirements, the package version doesn't get updated correctly. #1166</li> </ul>"},{"location":"dev/changelog/#miscellany_3","title":"Miscellany","text":"<ul> <li>Add additional installation option via asdf-pdm.   Add <code>skip-add-to-path</code> option to installer in order to prevent changing <code>PATH</code>.   Replace <code>bin</code> variable name with <code>bin_dir</code>. #1145</li> </ul>"},{"location":"dev/changelog/#release-v1153-2022-06-14","title":"Release v1.15.3 (2022-06-14)","text":""},{"location":"dev/changelog/#bug-fixes_66","title":"Bug Fixes","text":"<ul> <li>Fix a defect in the resolution preferences that causes an infinite resolution loop. #1119</li> <li>Update the poetry importer to support the new <code>[tool.poetry.build]</code> config table. #1131</li> </ul>"},{"location":"dev/changelog/#improved-documentation","title":"Improved Documentation","text":"<ul> <li>Add support for multiple versions of documentations. #1126</li> </ul>"},{"location":"dev/changelog/#release-v1152-2022-06-06","title":"Release v1.15.2 (2022-06-06)","text":""},{"location":"dev/changelog/#bug-fixes_67","title":"Bug Fixes","text":"<ul> <li>Fix bug where SIGINT is sent to the main <code>pdm</code> process and not to the process actually being run. #1095</li> <li>Fix a bug due to the build backend fallback, which causes different versions of the same requirement to exist in the build environment, making the building unstable depending on which version being used. #1099</li> <li>Don't include the <code>version</code> in the cache key of the locked candidates if they are from a URL requirement. #1099</li> <li>Fix a bug where dependencies with <code>requires-python</code> pre-release versions caused <code>pdm update</code> to fail with <code>InvalidPyVersion</code>. #1111</li> </ul>"},{"location":"dev/changelog/#release-v1151-2022-06-02","title":"Release v1.15.1 (2022-06-02)","text":""},{"location":"dev/changelog/#bug-fixes_68","title":"Bug Fixes","text":"<ul> <li>Fix a bug that dependencies are missing from the dep graph when they are depended by a requirement with extras. #1097</li> <li>Give a default version if the version is dynamic in <code>setup.cfg</code> or <code>setup.py</code>. #1101</li> <li>Fix a bug that the hashes for file URLs are not included in the lock file. #1103</li> <li>Fix a bug that package versions are updated even when they are excluded by <code>pdm update</code> command. #1104</li> <li>Prefer <code>venv</code> install scheme when available. This scheme is more stable than <code>posix_prefix</code> scheme since the latter is often patched by distributions. #1106</li> </ul>"},{"location":"dev/changelog/#miscellany_4","title":"Miscellany","text":"<ul> <li>Move the test artifacts to a submodule. It will make it easier to package this project. #1084</li> </ul>"},{"location":"dev/changelog/#release-v1150-2022-05-16","title":"Release v1.15.0 (2022-05-16)","text":""},{"location":"dev/changelog/#features-improvements_34","title":"Features &amp; Improvements","text":"<ul> <li>Allow specifying lockfile other than <code>pdm.lock</code> by <code>--lockfile</code> option or <code>PDM_LOCKFILE</code> env var. #1038</li> </ul>"},{"location":"dev/changelog/#bug-fixes_69","title":"Bug Fixes","text":"<ul> <li>Replace the editable entry in <code>pyproject.toml</code> when running <code>pdm add --no-editable &lt;package&gt;</code>. #1050</li> <li>Ensure the pip module inside venv in installation script. #1053</li> <li>Fix the py2 compatibility issue in the in-process <code>get_sysconfig_path.py</code> script. #1056</li> <li>Fix a bug that file paths in URLs are not correctly unquoted. #1073</li> <li>Fix a bug on Python 3.11 that overriding an existing command from plugins raises an error. #1075</li> <li>Replace the <code>${PROJECT_ROOT}</code> variable in the result of <code>export</code> command. #1079</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_7","title":"Removals and Deprecations","text":"<ul> <li>Show a warning if Python 2 interpreter is being used and remove the support on 2.0. #1082</li> </ul>"},{"location":"dev/changelog/#release-v1141-2022-04-21","title":"Release v1.14.1 (2022-04-21)","text":""},{"location":"dev/changelog/#features-improvements_35","title":"Features &amp; Improvements","text":"<ul> <li>Ask for description when doing <code>pdm init</code> and create default README for libraries. #1041</li> </ul>"},{"location":"dev/changelog/#bug-fixes_70","title":"Bug Fixes","text":"<ul> <li>Fix a bug of missing subdirectory fragment when importing from a <code>requirements.txt</code>. #1036</li> <li>Fix use_cache.json with corrupted python causes <code>pdm use</code> error. #1039</li> <li>Ignore the <code>optional</code> key when converting from Poetry's dependency entries. #1042</li> </ul>"},{"location":"dev/changelog/#improved-documentation_1","title":"Improved Documentation","text":"<ul> <li>Clarify documentation on enabling PEP582 globally. #1033</li> </ul>"},{"location":"dev/changelog/#release-v1140-2022-04-08","title":"Release v1.14.0 (2022-04-08)","text":""},{"location":"dev/changelog/#features-improvements_36","title":"Features &amp; Improvements","text":"<ul> <li>Editable installations won't be overridden unless <code>--no-editable</code> is passed.   <code>pdm add --no-editable</code> will now override the <code>editable</code> mode of the given packages. #1011</li> <li>Re-calculate the file hashes when running <code>pdm lock --refresh</code>. #1019</li> </ul>"},{"location":"dev/changelog/#bug-fixes_71","title":"Bug Fixes","text":"<ul> <li>Fix a bug that requirement with extras isn't resolved to the version as specified by the range. #1001</li> <li>Replace the <code>${PROJECT_ROOT}</code> in the output of <code>pdm list</code>. #1004</li> <li>Further fix the python path issue of macOS system installed Python. #1023</li> <li>Fix the install path issue on Python 3.10 installed from homebrew. #996</li> </ul>"},{"location":"dev/changelog/#improved-documentation_2","title":"Improved Documentation","text":"<ul> <li>Document how to install PDM inside a project with Pyprojectx. #1004</li> </ul>"},{"location":"dev/changelog/#dependencies_7","title":"Dependencies","text":"<ul> <li>Support <code>installer 0.5.x</code>. #1002</li> </ul>"},{"location":"dev/changelog/#release-v1136-2022-03-28","title":"Release v1.13.6 (2022-03-28)","text":""},{"location":"dev/changelog/#bug-fixes_72","title":"Bug Fixes","text":"<ul> <li>Default the optional <code>license</code> field to \"None\". #991</li> <li>Don't create project files in <code>pdm search</code> command. #993</li> <li>Fix a bug that the env vars in source urls in exported result are not expanded. #997</li> </ul>"},{"location":"dev/changelog/#release-v1135-2022-03-23","title":"Release v1.13.5 (2022-03-23)","text":""},{"location":"dev/changelog/#features-improvements_37","title":"Features &amp; Improvements","text":"<ul> <li>Users can change the install destination of global project to the user site(<code>~/.local</code>) with <code>global_project.user_site</code> config. #885</li> <li>Make the path to the global project configurable. Rename the configuration <code>auto_global</code> to <code>global_project.fallback</code> and deprecate the old name. #986</li> </ul>"},{"location":"dev/changelog/#bug-fixes_73","title":"Bug Fixes","text":"<ul> <li>Fix the compatibility when fetching license information in <code>show</code> command. #966</li> <li>Don't follow symlinks for the paths in the requirement strings. #976</li> <li>Use the default install scheme when installing build requirements. #983</li> <li>Fix a bug that <code>_.site_packages</code> is overridden by default option value. #985</li> </ul>"},{"location":"dev/changelog/#release-v1134-2022-03-09","title":"Release v1.13.4 (2022-03-09)","text":""},{"location":"dev/changelog/#features-improvements_38","title":"Features &amp; Improvements","text":"<ul> <li>Update the dependency <code>pdm-pep517</code> to support PEP 639. #959</li> </ul>"},{"location":"dev/changelog/#bug-fixes_74","title":"Bug Fixes","text":"<ul> <li>Filter out the unmatched python versions when listing the available versions. #941</li> <li>Fix a bug displaying the available python versions. #943</li> <li>Fix a bug under non-UTF8 console encoding. #960</li> <li>Fix a bug that data files are not copied to the destination when using installation cache. #961</li> </ul>"},{"location":"dev/changelog/#release-v1133-2022-02-24","title":"Release v1.13.3 (2022-02-24)","text":""},{"location":"dev/changelog/#bug-fixes_75","title":"Bug Fixes","text":"<ul> <li>Fix a bug that VCS repo name are parsed as the package name. #928</li> <li>Support prerelease versions for global projects. #932</li> <li>Fix a bug that VCS revision in the lock file isn't respected when installing. #933</li> </ul>"},{"location":"dev/changelog/#dependencies_8","title":"Dependencies","text":"<ul> <li>Switch from <code>pythonfinder</code> to <code>findpython</code> as the Python version finder. #930</li> </ul>"},{"location":"dev/changelog/#release-v1132-2022-02-20","title":"Release v1.13.2 (2022-02-20)","text":""},{"location":"dev/changelog/#bug-fixes_76","title":"Bug Fixes","text":"<ul> <li>Fix a regression issue that prereleases can't be installed if the version specifier of the requirement doesn't imply that. #920</li> </ul>"},{"location":"dev/changelog/#release-v1131-2022-02-18","title":"Release v1.13.1 (2022-02-18)","text":""},{"location":"dev/changelog/#bug-fixes_77","title":"Bug Fixes","text":"<ul> <li>Fix a bug that bad pip cache dir value breaks PDM's check update function. #922</li> <li>Fix a race condition in parallel installation by changing metadata to a lazy property.   This fixes a bug that incompatible wheels are installed unexpectedly. #924</li> </ul>"},{"location":"dev/changelog/#release-v1130post0-2022-02-18","title":"Release v1.13.0.post0 (2022-02-18)","text":""},{"location":"dev/changelog/#bug-fixes_78","title":"Bug Fixes","text":"<ul> <li>Fix a bug that incompatible platform-specific wheels are installed. #921</li> </ul>"},{"location":"dev/changelog/#release-v1130-2022-02-18","title":"Release v1.13.0 (2022-02-18)","text":""},{"location":"dev/changelog/#features-improvements_39","title":"Features &amp; Improvements","text":"<ul> <li>Support <code>pre_*</code> and <code>post_*</code> scripts for task composition. Pre- and Post- scripts for <code>init</code>, <code>build</code>, <code>install</code> and <code>lock</code> will be run if present. #789</li> <li>Support <code>--config/-c</code> option to specify another global configuration file. #883</li> <li>Packages with extras require no longer inherit the dependencies from the same package without extras. It is because the package without extras are returned as one of the dependencies. This change won't break the existing lock files nor dependency cache. #892</li> <li>Support version ranges in <code>[tool.pdm.overrides]</code> table. #909</li> <li>Rename config <code>use_venv</code> to <code>python.use_venv</code>;   rename config <code>feature.install_cache</code> to <code>install.cache</code>;   rename config <code>feature.install_cache_method</code> to <code>install.cache_method</code>;   rename config <code>parallel_install</code> to <code>install.parallel</code>. #914</li> </ul>"},{"location":"dev/changelog/#bug-fixes_79","title":"Bug Fixes","text":"<ul> <li>Fix a bug that file URLs or VCS URLs don't work in <code>[tool.pdm.overrides]</code> table. #861</li> <li>Fix a bug of identifier mismatch for URL requirements without an explicit name. #901</li> <li>No <code>requires-python</code> should be produced if ANY(<code>*</code>) is given. #917</li> <li>Fix a bug that <code>pdm.lock</code> gets created when <code>--dry-run</code> is passed to <code>pdm add</code>. #918</li> </ul>"},{"location":"dev/changelog/#improved-documentation_3","title":"Improved Documentation","text":"<ul> <li>The default editable backend becomes <code>path</code>. #904</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_8","title":"Removals and Deprecations","text":"<ul> <li>Stop auto-migrating projects from PDM 0.x format. #912</li> </ul>"},{"location":"dev/changelog/#refactor","title":"Refactor","text":"<ul> <li>Rename <code>ExtrasError</code> to <code>ExtrasWarning</code> for better understanding. Improve the warning message. #892</li> <li>Extract the environment related code from <code>Candidate</code> into a new class <code>PreparedCandidate</code>.   <code>Candidate</code> no longer holds an <code>Environment</code> instance. #920</li> </ul>"},{"location":"dev/changelog/#release-v1128-2022-02-06","title":"Release v1.12.8 (2022-02-06)","text":""},{"location":"dev/changelog/#features-improvements_40","title":"Features &amp; Improvements","text":"<ul> <li>Print the error and continue if a plugin fails to load. #878</li> </ul>"},{"location":"dev/changelog/#bug-fixes_80","title":"Bug Fixes","text":"<ul> <li>PDM now ignores configuration of uninstalled plugins. #872</li> <li>Fix the compatibility issue with <code>pip&gt;=22.0</code>. #875</li> </ul>"},{"location":"dev/changelog/#release-v1127-2022-01-31","title":"Release v1.12.7 (2022-01-31)","text":""},{"location":"dev/changelog/#features-improvements_41","title":"Features &amp; Improvements","text":"<ul> <li>If no command is given to <code>pdm run</code>, it will run the Python REPL. #856</li> </ul>"},{"location":"dev/changelog/#bug-fixes_81","title":"Bug Fixes","text":"<ul> <li>Fix the hash calculation when generating <code>direct_url.json</code> for a local pre-built wheel. #861</li> <li>PDM no longer migrates project meta silently. #867</li> </ul>"},{"location":"dev/changelog/#dependencies_9","title":"Dependencies","text":"<ul> <li>Pin <code>pip&lt;22.0</code>. #874</li> </ul>"},{"location":"dev/changelog/#miscellany_5","title":"Miscellany","text":"<ul> <li>Reduce the number of tests that require network, and mark the rest with <code>network</code> marker. #858</li> </ul>"},{"location":"dev/changelog/#release-v1126-2022-01-12","title":"Release v1.12.6 (2022-01-12)","text":""},{"location":"dev/changelog/#bug-fixes_82","title":"Bug Fixes","text":"<ul> <li>Fix a bug that cache dir isn't created. #843</li> </ul>"},{"location":"dev/changelog/#release-v1125-2022-01-11","title":"Release v1.12.5 (2022-01-11)","text":""},{"location":"dev/changelog/#bug-fixes_83","title":"Bug Fixes","text":"<ul> <li>Fix a resolution error that dots in the package name are normalized to <code>-</code> unexpectedly. #853</li> </ul>"},{"location":"dev/changelog/#release-v1124-2022-01-11","title":"Release v1.12.4 (2022-01-11)","text":""},{"location":"dev/changelog/#features-improvements_42","title":"Features &amp; Improvements","text":"<ul> <li>Remember the last selection in <code>use</code> command to save the human effort.   And introduce an <code>-i</code> option to ignored that remembered value. #846</li> </ul>"},{"location":"dev/changelog/#bug-fixes_84","title":"Bug Fixes","text":"<ul> <li>Fix a bug of uninstall crash when the package has directories in <code>RECORD</code>. #847</li> <li>Fix the <code>ModuleNotFoundError</code> during uninstall when the modules required are removed. #850</li> </ul>"},{"location":"dev/changelog/#release-v1123-2022-01-07","title":"Release v1.12.3 (2022-01-07)","text":""},{"location":"dev/changelog/#features-improvements_43","title":"Features &amp; Improvements","text":"<ul> <li>Support setting Python path in global configuration. #842</li> </ul>"},{"location":"dev/changelog/#bug-fixes_85","title":"Bug Fixes","text":"<ul> <li>Lowercase the package names in the lock file make it more stable. #836</li> <li>Show the packages to be updated in dry run mode of <code>pdm update</code> even if <code>--no-sync</code> is passed. #837</li> <li>Improve the robustness of update check code. #841</li> <li>Fix a bug that export result has environment markers that don't apply for all requirements. #843</li> </ul>"},{"location":"dev/changelog/#release-v1122-2021-12-30","title":"Release v1.12.2 (2021-12-30)","text":""},{"location":"dev/changelog/#features-improvements_44","title":"Features &amp; Improvements","text":"<ul> <li>Allow changing the installation linking method by <code>feature.install_cache_method</code> config. #822</li> </ul>"},{"location":"dev/changelog/#bug-fixes_86","title":"Bug Fixes","text":"<ul> <li>Fix a bug that namespace packages can't be symlinked to the cache due to existing links. #820</li> <li>Make PDM generated pth files processed as early as possible. #821</li> <li>Fix a UnicodeDecodeError for subprocess logger under Windows/GBK. #823</li> </ul>"},{"location":"dev/changelog/#release-v1121-2021-12-24","title":"Release v1.12.1 (2021-12-24)","text":""},{"location":"dev/changelog/#bug-fixes_87","title":"Bug Fixes","text":"<ul> <li>Don't symlink pycaches to the target place. #817</li> </ul>"},{"location":"dev/changelog/#release-v1120-2021-12-22","title":"Release v1.12.0 (2021-12-22)","text":""},{"location":"dev/changelog/#features-improvements_45","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>lock --refresh</code> to update the hash stored with the lock file without updating the pinned versions. #642</li> <li>Support resolution overriding in the <code>[tool.pdm.overrides]</code> table. #790</li> <li>Add support for signals for basic operations, now including <code>post_init</code>, <code>pre_lock</code>, <code>post_lock</code>, <code>pre_install</code> and <code>post_install</code>. #798</li> <li>Add <code>install --check</code> to check if the lock file is up to date. #810</li> <li>Use symlinks to cache installed packages when it is supported by the file system. #814</li> </ul>"},{"location":"dev/changelog/#bug-fixes_88","title":"Bug Fixes","text":"<ul> <li>Fix a bug that candidates from urls are rejected by the <code>allow_prereleases</code> setting.   Now non-named requirements are resolved earlier than pinned requirements. #799</li> </ul>"},{"location":"dev/changelog/#improved-documentation_4","title":"Improved Documentation","text":"<ul> <li>Add a new doc page: API reference. #802</li> </ul>"},{"location":"dev/changelog/#dependencies_10","title":"Dependencies","text":"<ul> <li>Switch back from <code>atoml</code> to <code>tomlkit</code> as the style-preserving TOML parser. The latter has supported TOML v1.0.0. #809</li> </ul>"},{"location":"dev/changelog/#miscellany_6","title":"Miscellany","text":"<ul> <li>Cache the latest version of PDM for one week to reduce the request frequency. #800</li> </ul>"},{"location":"dev/changelog/#release-v1113-2021-12-15","title":"Release v1.11.3 (2021-12-15)","text":""},{"location":"dev/changelog/#features-improvements_46","title":"Features &amp; Improvements","text":"<ul> <li>Change the default version save strategy to <code>minimum</code>, without upper bounds. #787</li> </ul>"},{"location":"dev/changelog/#bug-fixes_89","title":"Bug Fixes","text":"<ul> <li>Fix the patching of sysconfig in PEP 582 initialization script. #796</li> </ul>"},{"location":"dev/changelog/#miscellany_7","title":"Miscellany","text":"<ul> <li>Fix an installation failure of the bootstrap script on macOS Catalina. #793</li> <li>Add a basic benchmarking script. #794</li> </ul>"},{"location":"dev/changelog/#release-v1112-2021-12-10","title":"Release v1.11.2 (2021-12-10)","text":""},{"location":"dev/changelog/#bug-fixes_90","title":"Bug Fixes","text":"<ul> <li>Fix the resolution order to reduce the loop number to find a conflict. #781</li> <li>Patch the functions in <code>sysconfig</code> to return the PEP 582 scheme in <code>pdm run</code>. #784</li> </ul>"},{"location":"dev/changelog/#dependencies_11","title":"Dependencies","text":"<ul> <li>Remove the upper bound of version constraints for most dependencies, except for some zero-versioned ones. #787</li> </ul>"},{"location":"dev/changelog/#release-v1111-2021-12-08","title":"Release v1.11.1 (2021-12-08)","text":""},{"location":"dev/changelog/#features-improvements_47","title":"Features &amp; Improvements","text":"<ul> <li>Support <code>--pre/--prelease</code> option for <code>pdm add</code> and <code>pdm update</code>. It will allow prereleases to be pinned. #774</li> <li>Improve the error message when python is found but not meeting the python requirement. #777</li> </ul>"},{"location":"dev/changelog/#bug-fixes_91","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>git+https</code> candidates cannot be resolved. #771</li> <li>Fix an infinite resolution loop by resolving the top-level packages first. Also deduplicate the lines from the same requirement in the error output. #776</li> </ul>"},{"location":"dev/changelog/#miscellany_8","title":"Miscellany","text":"<ul> <li>Fix the install script to use a zipapp of virtualenv when it isn't installed. #780</li> </ul>"},{"location":"dev/changelog/#release-v1110-2021-11-30","title":"Release v1.11.0 (2021-11-30)","text":""},{"location":"dev/changelog/#features-improvements_48","title":"Features &amp; Improvements","text":"<ul> <li>Move <code>version</code> from <code>[project]</code> table to <code>[tool.pdm]</code> table, delete <code>classifiers</code> from <code>dynamic</code>, and warn usage about the deprecated usages. #748</li> <li>Add support for Conda environments in addition to Python virtual environments. #749</li> <li>Add support for saving only the lower bound <code>x &gt;= VERSION</code> when adding dependencies. #752</li> <li>Improve the error message when resolution fails. #754</li> </ul>"},{"location":"dev/changelog/#bug-fixes_92","title":"Bug Fixes","text":"<ul> <li>Switch to self-implemented <code>pdm list --freeze</code> to fix a bug due to Pip's API change. #533</li> <li>Fix an infinite loop issue when resolving candidates with incompatible <code>requires-python</code>. #744</li> <li>Fix the python finder to support pyenv-win. #745</li> <li>Fix the ANSI color output for Windows cmd and Powershell terminals. #753</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_9","title":"Removals and Deprecations","text":"<ul> <li>Remove <code>-s/--section</code> option from all previously supported commands. Use <code>-G/--group</code> instead. #756</li> </ul>"},{"location":"dev/changelog/#release-v1103-2021-11-18","title":"Release v1.10.3 (2021-11-18)","text":""},{"location":"dev/changelog/#bug-fixes_93","title":"Bug Fixes","text":"<ul> <li>Use <code>importlib</code> to replace <code>imp</code> in the <code>sitecustomize</code> module for Python 3. #574</li> <li>Fix the lib paths under non-isolated build. #740</li> <li>Exclude the dependencies with extras in the result of <code>pdm export</code>. #741</li> </ul>"},{"location":"dev/changelog/#release-v1102-2021-11-14","title":"Release v1.10.2 (2021-11-14)","text":""},{"location":"dev/changelog/#features-improvements_49","title":"Features &amp; Improvements","text":"<ul> <li>Add a new option <code>-s/--site-packages</code> to <code>pdm run</code> as well as a script config item. When it is set to <code>True</code>, site-packages from the selected interpreter will be loaded into the running environment. #733</li> </ul>"},{"location":"dev/changelog/#bug-fixes_94","title":"Bug Fixes","text":"<ul> <li>Now <code>NO_SITE_PACKAGES</code> isn't set in <code>pdm run</code> if the executable is out of local packages. #733</li> </ul>"},{"location":"dev/changelog/#release-v1101-2021-11-09","title":"Release v1.10.1 (2021-11-09)","text":""},{"location":"dev/changelog/#features-improvements_50","title":"Features &amp; Improvements","text":"<ul> <li>Isolate the project environment with system site packages in <code>pdm run</code>, but keep them seen when PEP 582 is enabled. #708</li> </ul>"},{"location":"dev/changelog/#bug-fixes_95","title":"Bug Fixes","text":"<ul> <li>Run <code>pip</code> with <code>--isolated</code> when building wheels. In this way some env vars like <code>PIP_REQUIRE_VIRTUALENV</code> can be ignored. #669</li> <li>Fix the install script to ensure <code>pip</code> is not DEBUNDLED. #685</li> <li>Fix a bug that when <code>summary</code> is <code>None</code>, the lockfile can't be generated. #719</li> <li><code>${PROJECT_ROOT}</code> should be written in the URL when relative path is given. #721</li> <li>Fix a bug that when project table already exists, <code>pdm import</code> can't merge the settings correctly. #723</li> </ul>"},{"location":"dev/changelog/#release-v1100-2021-10-25","title":"Release v1.10.0 (2021-10-25)","text":""},{"location":"dev/changelog/#features-improvements_51","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>--no-sync</code> option to <code>update</code> command. #684</li> <li>Support <code>find_links</code> source type. It can be specified via <code>type</code> key of <code>[[tool.pdm.source]]</code> table. #694</li> <li>Add <code>--dry-run</code> option to <code>add</code>, <code>install</code> and <code>remove</code> commands. #698</li> </ul>"},{"location":"dev/changelog/#bug-fixes_96","title":"Bug Fixes","text":"<ul> <li>Remove trailing whitespace with terminal output of tables (via <code>project.core.ui.display_columns</code>), fixing unnecessary wrapping due to / with empty lines full of spaces in case of long URLs in the last column. #680</li> <li>Include files should be installed under venv's base path. #682</li> <li>Ensure the value of <code>check_update</code> is boolean. #689</li> </ul>"},{"location":"dev/changelog/#improved-documentation_5","title":"Improved Documentation","text":"<ul> <li>Update the contributing guide, remove the usage of <code>setup_dev.py</code> in favor of <code>pip install</code>. #676</li> </ul>"},{"location":"dev/changelog/#release-v190-2021-10-12","title":"Release v1.9.0 (2021-10-12)","text":""},{"location":"dev/changelog/#bug-fixes_97","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>requires-python</code> is not recognized in candidates evaluation. #657</li> <li>Fix the path order when pdm run so that executables in local packages dir are found first. #678</li> </ul>"},{"location":"dev/changelog/#dependencies_12","title":"Dependencies","text":"<ul> <li>Update <code>installer</code> to <code>0.3.0</code>, fixing a bug that broke installation of some packages with unusual wheel files. #653</li> <li>Change <code>packaging</code> and <code>typing-extensions</code> to direct dependencies. #674</li> </ul>"},{"location":"dev/changelog/#refactor_1","title":"Refactor","text":"<ul> <li><code>requires-python</code> now participates in the resolution as a dummy requirement. #658</li> </ul>"},{"location":"dev/changelog/#release-v185-2021-09-16","title":"Release v1.8.5 (2021-09-16)","text":""},{"location":"dev/changelog/#bug-fixes_98","title":"Bug Fixes","text":"<ul> <li>Fix the error of regex to find the shebang line. #656</li> </ul>"},{"location":"dev/changelog/#release-v184-2021-09-15","title":"Release v1.8.4 (2021-09-15)","text":""},{"location":"dev/changelog/#features-improvements_52","title":"Features &amp; Improvements","text":"<ul> <li>Support <code>--no-isolation</code> option for <code>install</code>, <code>lock</code>, <code>update</code>, <code>remove</code>, <code>sync</code> commands. #640</li> <li>Make <code>project_max_depth</code> configurable and default to <code>5</code>. #643</li> </ul>"},{"location":"dev/changelog/#bug-fixes_99","title":"Bug Fixes","text":"<ul> <li>Don't try <code>pdm-pep517</code> backend on Python 2.7 when installing self as editable. #640</li> <li>Fix a bug that existing shebang can't be replaced correctly. #651</li> <li>Fix the version range saving for prerelease versions. #654</li> </ul>"},{"location":"dev/changelog/#release-v183-2021-09-07","title":"Release v1.8.3 (2021-09-07)","text":""},{"location":"dev/changelog/#features-improvements_53","title":"Features &amp; Improvements","text":"<ul> <li>Allow to build in non-isolated environment, to enable optional speedups depending on the environment. #635</li> </ul>"},{"location":"dev/changelog/#bug-fixes_100","title":"Bug Fixes","text":"<ul> <li>Don't copy <code>*-nspkg.pth</code> files in <code>install_cache</code> mode. It will still work without them. #623</li> </ul>"},{"location":"dev/changelog/#release-v182-2021-09-01","title":"Release v1.8.2 (2021-09-01)","text":""},{"location":"dev/changelog/#bug-fixes_101","title":"Bug Fixes","text":"<ul> <li>Fix the removal issue of standalone pyc files #633</li> </ul>"},{"location":"dev/changelog/#release-v181-2021-08-26","title":"Release v1.8.1 (2021-08-26)","text":""},{"location":"dev/changelog/#features-improvements_54","title":"Features &amp; Improvements","text":"<ul> <li>Add <code>-r/--reinstall</code> option to <code>sync</code> command to force re-install the existing dependencies. #601</li> <li>Show update hint after every pdm command. #603</li> <li><code>pdm cache clear</code> can clear cached installations if not needed any more. #604</li> </ul>"},{"location":"dev/changelog/#bug-fixes_102","title":"Bug Fixes","text":"<ul> <li>Fix the editable install script so that <code>setuptools</code> won't see the dependencies under local packages. #601</li> <li>Preserve the executable bit when installing wheels. #606</li> <li>Write PEP 610 metadata <code>direct_url.json</code> when installing wheels. #607</li> <li>Fix a bug that <code>*</code> fails to be converted as <code>SpecifierSet</code>. #609</li> </ul>"},{"location":"dev/changelog/#refactor_2","title":"Refactor","text":"<ul> <li>Build editable packages are into wheels via PEP 660 build backend. Now all installations are unified into wheels. #612</li> </ul>"},{"location":"dev/changelog/#release-v180-2021-08-16","title":"Release v1.8.0 (2021-08-16)","text":""},{"location":"dev/changelog/#features-improvements_55","title":"Features &amp; Improvements","text":"<ul> <li>Added a new mode <code>--json</code> to the list command which outputs the dependency graph as a JSON document. #583</li> <li>Add a new config <code>feature.install_cache</code>. When it is turned on, wheels will be installed into a centralized package repo and create <code>.pth</code> files under project packages directory to link to the cached package. #589</li> </ul>"},{"location":"dev/changelog/#bug-fixes_103","title":"Bug Fixes","text":"<ul> <li>Fix env vars in source URLs not being expanded in all cases. #570</li> <li>Fix the weird output of <code>pdm show</code>. #580</li> <li>Prefer <code>~/.pyenv/shims/python3</code> as the pyenv interpreter. #590</li> <li>Fix a bug that installing will download candidates that do not match the locked hashes. #596</li> </ul>"},{"location":"dev/changelog/#improved-documentation_6","title":"Improved Documentation","text":"<ul> <li>Added instructions to the Contributing section for creating news fragments #573</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_10","title":"Removals and Deprecations","text":"<ul> <li>Deprecate <code>-s/--section</code> option in favor of <code>-G/--group</code>. #591</li> </ul>"},{"location":"dev/changelog/#refactor_3","title":"Refactor","text":"<ul> <li>Switch to a self-implemented version of uninstaller. #586</li> <li><code>pdm/installers/installers.py</code> is renamed to <code>pdm/installers/manager.py</code> to be more accurate. The <code>Installer</code> class under that file is renamed to <code>InstallerManager</code> and is exposed in the <code>pdm.core.Core</code> object for overriding. The new <code>pdm/installers/installers.py</code> contains some installation implementations. #589</li> <li>Switch from <code>pkg_resources.Distribution</code> to the implementation of <code>importlib.metadata</code>. #592</li> </ul>"},{"location":"dev/changelog/#release-v172-2021-07-30","title":"Release v1.7.2 (2021-07-30)","text":""},{"location":"dev/changelog/#bug-fixes_104","title":"Bug Fixes","text":"<ul> <li>Remove the existing files before installing. #565</li> <li>Deduplicate the plugins list. #566</li> </ul>"},{"location":"dev/changelog/#release-v171-2021-07-29","title":"Release v1.7.1 (2021-07-29)","text":""},{"location":"dev/changelog/#bug-fixes_105","title":"Bug Fixes","text":"<ul> <li>Accept non-canonical distribution name in the wheel's dist-info directory name. #529</li> <li>Prefer requirements with narrower version constraints or allowing prereleases to find matches. #551</li> <li>Use the underlying real executable path for writing shebangs. #553</li> <li>Fix a bug that extra markers cannot be extracted when combined with other markers with \"and\". #559</li> <li>Fix a bug that redacted credentials in source urls get overwritten with the plain text after locking. #561</li> </ul>"},{"location":"dev/changelog/#refactor_4","title":"Refactor","text":"<ul> <li>Use installer as the wheel installer, replacing <code>distlib</code>. #519</li> </ul>"},{"location":"dev/changelog/#release-v170-2021-07-20","title":"Release v1.7.0 (2021-07-20)","text":""},{"location":"dev/changelog/#features-improvements_56","title":"Features &amp; Improvements","text":"<ul> <li>Support showing individual fields by <code>--&lt;field-name&gt;</code> options in pdm show. When no package is given, show this project. #527</li> <li>Add <code>--freeze</code> option to <code>pdm list</code> command which shows the dependencies list as pip's requirements.txt format. #531</li> </ul>"},{"location":"dev/changelog/#bug-fixes_106","title":"Bug Fixes","text":"<ul> <li>Fix the path manipulation on Windows, now the PEP 582 path is prepended to the <code>PYTHONPATH</code>. #522</li> <li>Fix the handling of auth prompting: will try keyring in non-verbose mode. #523</li> <li>Recognize old entry point name \"pdm.plugin\" for backward-compatibility. #530</li> <li>Match the VCS scheme in case-insensitive manner. #537</li> <li>Use the default permission bits when writing project files. #542</li> <li>Fix the VCS url to be consistent between lock and install. #547</li> </ul>"},{"location":"dev/changelog/#improved-documentation_7","title":"Improved Documentation","text":"<ul> <li>Add installation instructions for Scoop. #522</li> </ul>"},{"location":"dev/changelog/#dependencies_13","title":"Dependencies","text":"<ul> <li>Update <code>pdm-pep517</code> to <code>0.8.0</code>. #524</li> <li>Switch from <code>toml</code> to <code>tomli</code>. #541</li> </ul>"},{"location":"dev/changelog/#refactor_5","title":"Refactor","text":"<ul> <li>Separate the build env into two different levels for better caching. #541</li> <li>Refactor the build part into smaller functions. #543</li> </ul>"},{"location":"dev/changelog/#release-v164-2021-06-23","title":"Release v1.6.4 (2021-06-23)","text":""},{"location":"dev/changelog/#features-improvements_57","title":"Features &amp; Improvements","text":"<ul> <li>Extract package name from egg-info in filename when eligible. Remove the patching code of resolvelib's inner class. #441</li> <li>Support installing packages from subdiretories of VCS repository. #507</li> <li>Add an install script to bootstrap PDM quickly without help of other tools. Modify docs to recommend this installation method. #508</li> <li>Add a new subcommand <code>plugin</code> to manage pdm plugins, including <code>add</code>, <code>remove</code> and <code>list</code> commands. #510</li> </ul>"},{"location":"dev/changelog/#bug-fixes_107","title":"Bug Fixes","text":"<ul> <li>Don't monkeypatch the internal class of <code>resolvelib</code> any more. This makes PDM more stable across updates of sub-dependencies. #515</li> </ul>"},{"location":"dev/changelog/#miscellany_9","title":"Miscellany","text":"<ul> <li>Clear the type errors from mypy. #261</li> </ul>"},{"location":"dev/changelog/#release-v163-2021-06-17","title":"Release v1.6.3 (2021-06-17)","text":""},{"location":"dev/changelog/#features-improvements_58","title":"Features &amp; Improvements","text":"<ul> <li>Add an option <code>-u/--unconstrained</code> to support unconstraining version specifiers when adding packages. #501</li> </ul>"},{"location":"dev/changelog/#bug-fixes_108","title":"Bug Fixes","text":"<ul> <li>Fix the format of dependency arrays when a new value is appended. #487</li> <li>Allow missing email attribute for authors and maintainers. #492</li> <li>Fix a bug that editable install shouldn't require pyproject.toml to be valid. #497</li> <li>Fix a bug on macOS that purelib and platlib paths of isolated build envs cannot be substituted correctly if the Python is a framework build. #502</li> <li>Fix the version sort of candidates. #506</li> </ul>"},{"location":"dev/changelog/#release-v162-2021-05-31","title":"Release v1.6.2 (2021-05-31)","text":"<p>No significant changes.</p>"},{"location":"dev/changelog/#release-v161-2021-05-31","title":"Release v1.6.1 (2021-05-31)","text":"<p>No significant changes.</p>"},{"location":"dev/changelog/#release-v160-2021-05-31","title":"Release v1.6.0 (2021-05-31)","text":""},{"location":"dev/changelog/#features-improvements_59","title":"Features &amp; Improvements","text":"<ul> <li>Use a new approach to determine the packages to be installed. This requires a quick resolution step before installation. #456</li> <li><code>pdm export</code> no longer produces requirements file applicable for all platforms due to the new approach. #456</li> <li>Add structural typing for requirements module. Refactor the requirements module for that purpose. #433</li> <li>Introduce <code>--no-editable</code> option to install non-editable versions of all packages. #443</li> <li>Introduce <code>--no-self</code> option to prevent the project itself from being installed. #444</li> <li>Add a default <code>.gitignore</code> file in the <code>__pypackages__</code> directory. #446</li> <li>Check if the lock file version is compatible with PDM program before installation. #463</li> <li>Expose the project root path via <code>PDM_PROJECT_ROOT</code> env var. Change to the project root when executing scripts. #470</li> <li>Fix a bug that installation resolution doesn't respect the requirement markers from pyproject config. #480</li> </ul>"},{"location":"dev/changelog/#bug-fixes_109","title":"Bug Fixes","text":"<ul> <li>Changing to multiline breaks the parsing of TOML document. #462</li> <li>Fix a bug that transient dependencies of conditional requirements can't be resolved. #472</li> <li>Fix a bug that invalid wheels are rejected while they are acceptable for resolution. #473</li> <li>Fix a bug that build environment is not fully isolated with the hosted environment. #477</li> <li>Ensure the lock file is compatible before looking for the locked candidates. #484</li> </ul>"},{"location":"dev/changelog/#improved-documentation_8","title":"Improved Documentation","text":"<ul> <li>Fix 404 links in documentation. #472</li> </ul>"},{"location":"dev/changelog/#dependencies_14","title":"Dependencies","text":"<ul> <li>Migrate from <code>tomlkit</code> to <code>atoml</code> as the style-preserving TOML parser and writer. #465</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_11","title":"Removals and Deprecations","text":"<ul> <li>Remove the warning of <code>--dev</code> flag for older versions of PDM. #444</li> </ul>"},{"location":"dev/changelog/#miscellany_10","title":"Miscellany","text":"<ul> <li>Add Python 3.10 beta CI job. #457</li> </ul>"},{"location":"dev/changelog/#release-v153-2021-05-10","title":"Release v1.5.3 (2021-05-10)","text":""},{"location":"dev/changelog/#features-improvements_60","title":"Features &amp; Improvements","text":"<ul> <li>Support passing options to the build backends via <code>--config-setting</code>. #452</li> </ul>"},{"location":"dev/changelog/#bug-fixes_110","title":"Bug Fixes","text":"<ul> <li>Seek for other sitecustomize.py to import. #422</li> <li>Fix an unescaped single quote in fish completion script. #423</li> <li>The hashes of a remote file candidate should be calculated from the link itself. #450</li> </ul>"},{"location":"dev/changelog/#dependencies_15","title":"Dependencies","text":"<ul> <li>Remove <code>keyring</code> as a dependency and guide users to install it when it is not available. #442</li> <li>Specify the minimum version of <code>distlib</code>. #447</li> </ul>"},{"location":"dev/changelog/#miscellany_11","title":"Miscellany","text":"<ul> <li>Add log output about found candidates and their origin. #421</li> <li>Add mypy pre-commit hook #427</li> <li>Improve type safety of <code>pdm.cli.actions</code> #428</li> <li>Fix wrong mypy configuration. #451</li> </ul>"},{"location":"dev/changelog/#release-v152-2021-04-27","title":"Release v1.5.2 (2021-04-27)","text":""},{"location":"dev/changelog/#features-improvements_61","title":"Features &amp; Improvements","text":"<ul> <li>Allow <code>pdm use</code> with no argument given, which will list all available pythons for pick. #409</li> </ul>"},{"location":"dev/changelog/#bug-fixes_111","title":"Bug Fixes","text":"<ul> <li>Inform user to enable PEP 582 for development script to work. #404</li> <li>Check the existence of pyenv shim Python interpreter before using it. #406</li> <li>Fix a bug that executing <code>setup.py</code> failed for NameError. #407</li> <li>Check before setting the PYTHONPATH environment variable for PEP582 #410</li> <li>Fix development setup error. #415</li> </ul>"},{"location":"dev/changelog/#dependencies_16","title":"Dependencies","text":"<ul> <li>Update pip to 21.1 and fix compatibility issues. #412</li> </ul>"},{"location":"dev/changelog/#release-v151-2021-04-22","title":"Release v1.5.1 (2021-04-22)","text":""},{"location":"dev/changelog/#bug-fixes_112","title":"Bug Fixes","text":"<ul> <li>Make func translate_sections pure to avoid exporting requirements in random order. #401</li> <li>Expand the variables in install requirements' attributes for build. #402</li> </ul>"},{"location":"dev/changelog/#release-v150-2021-04-20","title":"Release v1.5.0 (2021-04-20)","text":""},{"location":"dev/changelog/#features-improvements_62","title":"Features &amp; Improvements","text":"<ul> <li>Include dev dependencies by default for <code>install</code> and <code>sync</code> commands. Add a new option <code>--prod/--production</code> to exclude them. Improve the dependency selection logic to be more convenient to use \u2014 the more common the usage is, the shorter the command is. #391</li> </ul>"},{"location":"dev/changelog/#bug-fixes_113","title":"Bug Fixes","text":"<ul> <li>Enquote executable path to ensure generating valid scripts. #387</li> <li>Consider hashes when fetching artifact link for build. #389</li> <li>Considier the sources settings when building. #399</li> </ul>"},{"location":"dev/changelog/#improved-documentation_9","title":"Improved Documentation","text":"<ul> <li>New pdm setting <code>source-includes</code> to mark files to be included only in sdist builds. #390</li> </ul>"},{"location":"dev/changelog/#dependencies_17","title":"Dependencies","text":"<ul> <li>Update <code>pdm-pep517</code> to <code>0.7.0</code>; update <code>resolvelib</code> to<code>0.7.0</code>. #390</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_12","title":"Removals and Deprecations","text":"<ul> <li>Deprecate the usage of <code>-d/--dev</code> option in <code>install</code> and <code>sync</code> commands. #391</li> </ul>"},{"location":"dev/changelog/#release-v150b1-2021-04-12","title":"Release v1.5.0b1 (2021-04-12)","text":""},{"location":"dev/changelog/#features-improvements_63","title":"Features &amp; Improvements","text":"<ul> <li>Improve the env builder to run in isolated mode. #384</li> </ul>"},{"location":"dev/changelog/#bug-fixes_114","title":"Bug Fixes","text":"<ul> <li>Remove the incompatible code from the files that will be run in-process. #375</li> <li>Get the correct Python ABI tag of selected interpreter #378</li> <li>Error out when doing <code>pdm run</code> on a directory not initialized yet.</li> <li>Give warning message when the project automatically fallbacks to the global project.</li> </ul>"},{"location":"dev/changelog/#dependencies_18","title":"Dependencies","text":"<ul> <li>Upgrade <code>resolvelib</code> to <code>0.6.0</code>. #381</li> </ul>"},{"location":"dev/changelog/#miscellany_12","title":"Miscellany","text":"<ul> <li>refactor <code>pdm.models.readers</code> to improve typing support #321</li> <li>Add a basic integration test for cross-python check. #377</li> <li>Refactor the <code>project.python_executable</code> to <code>project.python</code> that contains all info of the interpreter. #382</li> <li>Continue refactoring Python info to extract to its own module. #383</li> <li>Refactor the creation of project.</li> </ul>"},{"location":"dev/changelog/#release-v150b0-2021-04-03","title":"Release v1.5.0b0 (2021-04-03)","text":""},{"location":"dev/changelog/#features-improvements_64","title":"Features &amp; Improvements","text":"<ul> <li>Add hand-written zsh completion script. #188</li> <li>Add a special value <code>:all</code> given to <code>-s/--section</code> to refer to all sections under the same species.   Adjust <code>add</code>, <code>sync</code>, <code>install</code>, <code>remove</code> and <code>update</code> to support the new <code>dev-dependencies</code> groups. Old behavior will be kept the same. #351</li> <li><code>dev-dependencies</code> is now a table of dependencies groups, where key is the group name and value is an array of dependencies. These dependencies won't appear in the distribution's metadata. <code>dev-depedencies</code> of the old format will turn into <code>dev</code> group under <code>dev-dependencies</code>. #351</li> <li>Move <code>dev-dependencies</code>, <code>includes</code>, <code>excludes</code> and <code>package-dir</code> out from <code>[project]</code> table to <code>[tool.pdm]</code> table. The migration will be done automatically if old format is detected. #351</li> <li>Throws an error with meaningful message when no candidate is found for one requirement. #357</li> <li>Support <code>--dry-run</code> option for <code>update</code> command to display packages that need update, install or removal. Add <code>--top</code> option to limit to top level packages only. #358</li> <li>Full-featured completion scripts for Zsh and Powershell - section selection, package name autocompletion and so on. Windows is a first-class citizen! #367</li> <li>Support non-interactive <code>init</code> command via <code>-n/--non-interactive</code> option. No question will be asked in this mode. #368</li> <li>Show project packages path(PEP 582) in the output of <code>pdm info</code>, also add an option <code>--packages</code> to show that value only. #372</li> </ul>"},{"location":"dev/changelog/#bug-fixes_115","title":"Bug Fixes","text":"<ul> <li>Fix a bug that pure python libraries are not loaded to construct the WorkingSet. #346</li> <li>Don't write <code>&lt;script&gt;-X.Y</code> variant to the bin folder. #365</li> <li>Python is now run in isolated mode via subprocess to avoid accidentally importing user packages. #369</li> <li>Don't overwrite existing dependencies when importing from requirements.txt. #370</li> </ul>"},{"location":"dev/changelog/#improved-documentation_10","title":"Improved Documentation","text":"<ul> <li>Add instructions of how to integrate PDM with Emacs, contributed by @linw1995. #372</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_13","title":"Removals and Deprecations","text":"<ul> <li>Remove the support of project path following <code>-g/--global</code> that was deprecated in <code>1.4.0</code>. One should use <code>-g -p &lt;project_path&gt;</code> for that purpose. #361</li> </ul>"},{"location":"dev/changelog/#miscellany_13","title":"Miscellany","text":"<ul> <li>Add test coverage to PDM. #109</li> <li>Add type annotations into untyped functions to start using mypy. #354</li> <li>Refactor the format converter code to be more explicit. #360</li> </ul>"},{"location":"dev/changelog/#release-v145-2021-03-30","title":"Release v1.4.5 (2021-03-30)","text":""},{"location":"dev/changelog/#features-improvements_65","title":"Features &amp; Improvements","text":"<ul> <li>Skip the first prompt of <code>pdm init</code> #352</li> </ul>"},{"location":"dev/changelog/#bug-fixes_116","title":"Bug Fixes","text":"<ul> <li>Fix a test failure when using homebrew installed python. #348</li> <li>Get revision from the VCS URL if source code isn't downloaded to local. #349</li> </ul>"},{"location":"dev/changelog/#dependencies_19","title":"Dependencies","text":"<ul> <li>Update dependency <code>pdm-pep517</code> to <code>0.6.1</code>. #353</li> </ul>"},{"location":"dev/changelog/#release-v144-2021-03-27","title":"Release v1.4.4 (2021-03-27)","text":""},{"location":"dev/changelog/#features-improvements_66","title":"Features &amp; Improvements","text":"<ul> <li>Emit warning if version or description can't be retrieved when importing from flit metadata. #342</li> <li>Add <code>type</code> argument to <code>pdm cache clear</code> and improve its UI. #343</li> <li>Always re-install the editable packages when syncing the working set. This can help tracking the latest change of <code>entry-points</code>. #344</li> </ul>"},{"location":"dev/changelog/#bug-fixes_117","title":"Bug Fixes","text":"<ul> <li>Make installer quit early if a wheel isn't able to build. #338</li> </ul>"},{"location":"dev/changelog/#miscellany_14","title":"Miscellany","text":"<ul> <li>ignore type checking in <code>models.project_info.ProjectInfo</code>, which indexes <code>distlib.metadata._data</code> #335</li> </ul>"},{"location":"dev/changelog/#release-v143-2021-03-24","title":"Release v1.4.3 (2021-03-24)","text":""},{"location":"dev/changelog/#features-improvements_67","title":"Features &amp; Improvements","text":"<ul> <li>Change the group name of entry points from <code>pdm.plugins</code> to <code>pdm</code>.   Export some useful objects and models for shorter import path. #318</li> <li>Field <code>cmd</code> in <code>tools.pdm.scripts</code> configuration items now allows specifying an argument array instead of a string.</li> <li>Refactor: Remove the reference of <code>stream</code> singleton, improve the UI related code. #320</li> <li>Support dependencies managed by poetry and flit being installed as editable packages. #324</li> <li>Refactor: Extract the logic of finding interpreters to method for the sake of subclass overriding. #326</li> <li>Complete the <code>cache</code> command, add <code>list</code>, <code>remove</code> and <code>info</code> subcommands. #329</li> <li>Refactor: Unify the code about selecting interpreter to reduce the duplication. #331</li> <li>Retrieve the version and description of a flit project by parsing the AST of the main file. #333</li> </ul>"},{"location":"dev/changelog/#bug-fixes_118","title":"Bug Fixes","text":"<ul> <li>Fix a parsing error when non-ascii characters exist in <code>pyproject.toml</code>. #308</li> <li>Fix a bug that non-editable VCS candidates can't satisfy their requirements once locked in the lock file. #314</li> <li>Fix a bug of import-on-init that fails when requirements.txt is detected. #328</li> </ul>"},{"location":"dev/changelog/#miscellany_15","title":"Miscellany","text":"<ul> <li>refactor <code>pdm.iostream</code> to improve 'typing' support #301</li> <li>fix some typos #323</li> </ul>"},{"location":"dev/changelog/#release-v142-2021-03-18","title":"Release v1.4.2 (2021-03-18)","text":""},{"location":"dev/changelog/#features-improvements_68","title":"Features &amp; Improvements","text":"<ul> <li>Refactor the code, extract the version related logic from <code>specifiers.py</code> to a separated module. #303</li> </ul>"},{"location":"dev/changelog/#bug-fixes_119","title":"Bug Fixes","text":"<ul> <li>Fix a bug that get_dependencies() returns error when the <code>setup.py</code> has no <code>intall_requires</code> key. #299</li> <li>Pin the VCS revision for non-editable VCS candidates in the lock file. #305</li> <li>Fix a bug that editable build hits the cached wheel unexpectedly. #307</li> </ul>"},{"location":"dev/changelog/#miscellany_16","title":"Miscellany","text":"<ul> <li>replace 'typing comments' with type annotations throughout #298</li> </ul>"},{"location":"dev/changelog/#release-v141-2021-03-12","title":"Release v1.4.1 (2021-03-12)","text":""},{"location":"dev/changelog/#features-improvements_69","title":"Features &amp; Improvements","text":"<ul> <li>Support importing dependencies from requirements.txt to dev-dependencies or sections. #291</li> </ul>"},{"location":"dev/changelog/#bug-fixes_120","title":"Bug Fixes","text":"<ul> <li>Fallback to static parsing when building was failed to find the dependencies of a candidate. #293</li> <li>Fix a bug that <code>pdm init</code> fails when <code>pyproject.toml</code> exists but has no <code>[project]</code> section. #295</li> </ul>"},{"location":"dev/changelog/#improved-documentation_11","title":"Improved Documentation","text":"<ul> <li>Document about how to use PDM with Nox. #281</li> </ul>"},{"location":"dev/changelog/#release-v140-2021-03-05","title":"Release v1.4.0 (2021-03-05)","text":""},{"location":"dev/changelog/#features-improvements_70","title":"Features &amp; Improvements","text":"<ul> <li>When <code>-I/--ignore-python</code> passed or <code>PDM_IGNORE_SAVED_PYTHON=1</code>, ignore the interpreter set in <code>.pdm.toml</code> and don't save to it afterwards. #283</li> <li>A new option <code>-p/--project</code> is introduced to specify another path for the project base. It can also be combined with <code>-g/--global</code> option.   The latter is changed to a flag only option that does not accept values. #286</li> <li>Support <code>-f setuppy</code> for <code>pdm export</code> to export the metadata as setup.py #289</li> </ul>"},{"location":"dev/changelog/#bug-fixes_121","title":"Bug Fixes","text":"<ul> <li>Fix a bug that editable local package requirements cannot be parsed rightly. #285</li> <li>Change the priority of metadata files to parse so that PEP 621 metadata will be parsed first. #288</li> </ul>"},{"location":"dev/changelog/#improved-documentation_12","title":"Improved Documentation","text":"<ul> <li>Add examples of how to integrate with CI pipelines (and tox). #281</li> </ul>"},{"location":"dev/changelog/#release-v134-2021-03-01","title":"Release v1.3.4 (2021-03-01)","text":""},{"location":"dev/changelog/#improved-documentation_13","title":"Improved Documentation","text":"<ul> <li>added documentation on a task provider for vscode #280</li> </ul>"},{"location":"dev/changelog/#bug-fixes_122","title":"Bug Fixes","text":"<ul> <li>Ignore the python requires constraints when fetching the link from the PyPI index.</li> </ul>"},{"location":"dev/changelog/#release-v133-2021-02-26","title":"Release v1.3.3 (2021-02-26)","text":""},{"location":"dev/changelog/#bug-fixes_123","title":"Bug Fixes","text":"<ul> <li>Fix the requirement string of a VCS requirement to comply with PEP 508. #275</li> <li>Fix a bug that editable packages with <code>src</code> directory can't be uninstalled correctly. #277</li> <li>Fix a bug that editable package doesn't override the non-editable version in the working set. #278</li> </ul>"},{"location":"dev/changelog/#release-v132-2021-02-25","title":"Release v1.3.2 (2021-02-25)","text":""},{"location":"dev/changelog/#features-improvements_71","title":"Features &amp; Improvements","text":"<ul> <li>Abort and tell user the selected section following <code>pdm sync</code> or <code>pdm install</code> is not present in the error message. #274</li> </ul>"},{"location":"dev/changelog/#bug-fixes_124","title":"Bug Fixes","text":"<ul> <li>Fix a bug that candidates' sections cannot be retrieved rightly when circular dependencies exist. #270</li> <li>Don't pass the help argument into the run script method. #272</li> </ul>"},{"location":"dev/changelog/#release-v131-2021-02-19","title":"Release v1.3.1 (2021-02-19)","text":""},{"location":"dev/changelog/#bug-fixes_125","title":"Bug Fixes","text":"<ul> <li>Use the absolute path when importing from a Poetry pyproject.toml. #262</li> <li>Fix a bug that old toml table head is kept when converting to PEP 621 metadata format. #263</li> <li>Postpone the evaluation of <code>requires-python</code> attribute when fetching the candidates of a package. #264</li> </ul>"},{"location":"dev/changelog/#release-v130-2021-02-09","title":"Release v1.3.0 (2021-02-09)","text":""},{"location":"dev/changelog/#features-improvements_72","title":"Features &amp; Improvements","text":"<ul> <li>Increase the default value of the max rounds of resolution to 1000, make it configurable. #238</li> <li>Rewrite the project's <code>egg-info</code> directory when dependencies change. So that <code>pdm list --graph</code> won't show invalid entries. #240</li> <li>When importing requirements from a <code>requirements.txt</code> file, build the package to find the name if not given in the URL. #245</li> <li>When initializing the project, prompt user for whether the project is a library, and give empty <code>name</code> and <code>version</code> if not. #253</li> </ul>"},{"location":"dev/changelog/#bug-fixes_126","title":"Bug Fixes","text":"<ul> <li>Fix the version validator of wheel metadata to align with the implementation of <code>packaging</code>. #130</li> <li>Preserve the <code>sections</code> value of a pinned candidate to be reused. #234</li> <li>Strip spaces in user input when prompting for the python version to use. #252</li> <li>Fix the version parsing of Python requires to allow <code>&gt;</code>, <code>&gt;=</code>, <code>&lt;</code>, <code>&lt;=</code> to combine with star versions. #254</li> </ul>"},{"location":"dev/changelog/#release-v120-2021-01-26","title":"Release v1.2.0 (2021-01-26)","text":""},{"location":"dev/changelog/#features-improvements_73","title":"Features &amp; Improvements","text":"<ul> <li>Change the behavior of <code>--save-compatible</code> slightly. Now the version specifier saved is using the REAL compatible operator <code>~=</code> as described in PEP 440. Before: <code>requests&lt;3.0.0,&gt;=2.19.1</code>, After: <code>requests~=2.19</code>. The new specifier accepts <code>requests==2.19.0</code> as compatible version. #225</li> <li>Environment variable <code>${PROJECT_ROOT}</code> in the dependency specification can be expanded to refer to the project root in pyproject.toml.   The environment variables will be kept as they are in the lock file. #226</li> <li>Change the dependencies of a package in the lock file to a list of PEP 508 strings #236</li> </ul>"},{"location":"dev/changelog/#bug-fixes_127","title":"Bug Fixes","text":"<ul> <li>Ignore user's site and <code>PYTHONPATH</code>(with <code>python -I</code> mode) when executing pip commands. #231</li> </ul>"},{"location":"dev/changelog/#improved-documentation_14","title":"Improved Documentation","text":"<ul> <li>Document about how to activate and use a plugin. #227</li> </ul>"},{"location":"dev/changelog/#dependencies_20","title":"Dependencies","text":"<ul> <li>Test project on <code>pip 21.0</code>. #235</li> </ul>"},{"location":"dev/changelog/#release-v110-2021-01-18","title":"Release v1.1.0 (2021-01-18)","text":""},{"location":"dev/changelog/#features-improvements_74","title":"Features &amp; Improvements","text":"<ul> <li>Allow users to hide secrets from the <code>pyproject.toml</code>.</li> <li>Dynamically expand env variables in the URLs in dependencies and indexes.</li> <li>Ask whether to store the credentials provided by the user.</li> <li>A user-friendly error will show when credentials are not provided nor correct. #198</li> <li>Use a different package dir for 32-bit installation(Windows). #212</li> <li>Auto disable PEP 582 when a venv-like python is given as the interpreter path. #219</li> <li>Support specifying Python interpreter by <code>pdm use &lt;path-to-python-root&gt;</code>. #221</li> </ul>"},{"location":"dev/changelog/#bug-fixes_128","title":"Bug Fixes","text":"<ul> <li>Fix a bug of <code>PYTHONPATH</code> manipulation under Windows platform. #215</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_14","title":"Removals and Deprecations","text":"<ul> <li>Remove support of the old PEP 517 backend API path. #217</li> </ul>"},{"location":"dev/changelog/#release-v100-2021-01-05","title":"Release v1.0.0 (2021-01-05)","text":""},{"location":"dev/changelog/#bug-fixes_129","title":"Bug Fixes","text":"<ul> <li>Correctly build wheels for dependencies with build-requirements but without a specified build-backend #213</li> </ul>"},{"location":"dev/changelog/#release-v100b2-2020-12-29","title":"Release v1.0.0b2 (2020-12-29)","text":""},{"location":"dev/changelog/#features-improvements_75","title":"Features &amp; Improvements","text":"<ul> <li>Fallback to pypi.org when <code>/search</code> endpoint is not available on given index. #211</li> </ul>"},{"location":"dev/changelog/#bug-fixes_130","title":"Bug Fixes","text":"<ul> <li>Fix a bug that PDM fails to parse python version specifiers with more than 3 parts. #210</li> </ul>"},{"location":"dev/changelog/#release-v100b0-2020-12-24","title":"Release v1.0.0b0 (2020-12-24)","text":""},{"location":"dev/changelog/#features-improvements_76","title":"Features &amp; Improvements","text":"<ul> <li>Fully support of PEP 621 specification.</li> <li>Old format is deprecated at the same time.</li> <li>PDM will migrate the project file for you when old format is detected.</li> <li>Other metadata formats(<code>Poetry</code>, <code>Pipfile</code>, <code>flit</code>) can also be imported as PEP 621 metadata. #175</li> <li>Re-implement the <code>pdm search</code> to query the <code>/search</code> HTTP endpoint. #195</li> <li>Reuse the cached built wheels to accelerate the installation. #200</li> <li>Make update strategy and save strategy configurable in pdm config. #202</li> <li>Improve the error message to give more insight on what to do when resolution fails. #207</li> <li>Set <code>classifiers</code> dynamic in <code>pyproject.toml</code> template for autogeneration. #209</li> </ul>"},{"location":"dev/changelog/#bug-fixes_131","title":"Bug Fixes","text":"<ul> <li>Fix a bug that distributions are not removed clearly in parallel mode. #204</li> <li>Fix a bug that python specifier <code>is_subset()</code> returns incorrect result. #206</li> </ul>"},{"location":"dev/changelog/#release-v0123-2020-12-21","title":"Release v0.12.3 (2020-12-21)","text":""},{"location":"dev/changelog/#dependencies_21","title":"Dependencies","text":"<ul> <li>Pin <code>pdm-pep517</code> to <code>&lt;0.3.0</code>, this is the last version to support legacy project metadata format.</li> </ul>"},{"location":"dev/changelog/#release-v0122-2020-12-17","title":"Release v0.12.2 (2020-12-17)","text":""},{"location":"dev/changelog/#features-improvements_77","title":"Features &amp; Improvements","text":"<ul> <li>Update the lock file schema, move the file hashes to <code>[metadata.files]</code> table. #196</li> <li>Retry failed jobs when syncing packages. #197</li> </ul>"},{"location":"dev/changelog/#removals-and-deprecations_15","title":"Removals and Deprecations","text":"<ul> <li>Drop <code>pip-shims</code> package as a dependency. #132</li> </ul>"},{"location":"dev/changelog/#miscellany_17","title":"Miscellany","text":"<ul> <li>Fix the cache path for CI. #199</li> </ul>"},{"location":"dev/changelog/#release-v0121-2020-12-14","title":"Release v0.12.1 (2020-12-14)","text":""},{"location":"dev/changelog/#features-improvements_78","title":"Features &amp; Improvements","text":"<ul> <li>Provide an option to export requirements from pyproject.toml #190</li> <li>For Windows users, <code>pdm --pep582</code> can enable PEP 582 globally by manipulating the WinReg. #191</li> </ul>"},{"location":"dev/changelog/#bug-fixes_132","title":"Bug Fixes","text":"<ul> <li>Inject <code>__pypackages__</code> into <code>PATH</code> env var during <code>pdm run</code>. #193</li> </ul>"},{"location":"dev/changelog/#release-v0120-2020-12-08","title":"Release v0.12.0 (2020-12-08)","text":""},{"location":"dev/changelog/#features-improvements_79","title":"Features &amp; Improvements","text":"<ul> <li>Improve the user experience of <code>pdm run</code>:</li> <li>Add a special key in tool.pdm.scripts that holds configurations shared by all scripts.</li> <li>Support loading env var from a dot-env file.</li> <li>Add a flag <code>-s/--site-packages</code> to include system site-packages when running. #178</li> <li>Now PEP 582 can be enabled in the Python interpreter directly! #181</li> </ul>"},{"location":"dev/changelog/#bug-fixes_133","title":"Bug Fixes","text":"<ul> <li>Ensure <code>setuptools</code> is installed before invoking editable install script. #174</li> <li>Require <code>wheel</code> not <code>wheels</code> for global projects #182</li> <li>Write a <code>sitecustomize.py</code> instead of a <code>.pth</code> file to enable PEP 582. Thanks @Aloxaf.   Update <code>get_package_finder()</code> to be compatible with <code>pip 20.3</code>. #185</li> <li>Fix the help messages of commands \"cache\" and \"remove\" #187</li> </ul>"},{"location":"dev/changelog/#release-v0110-2020-11-20","title":"Release v0.11.0 (2020-11-20)","text":""},{"location":"dev/changelog/#features-improvements_80","title":"Features &amp; Improvements","text":"<ul> <li>Support custom script shortcuts in <code>pyproject.toml</code>.</li> <li>Support custom script shortcuts defined in <code>[tool.pdm.scripts]</code> section.</li> <li>Add <code>pdm run --list/-l</code> to show the list of script shortcuts. #168</li> <li>Patch the halo library to support parallel spinners.</li> <li>Change the looking of <code>pdm install</code>. #169</li> </ul>"},{"location":"dev/changelog/#bug-fixes_134","title":"Bug Fixes","text":"<ul> <li>Fix a bug that package's marker fails to propagate to its grandchildren if they have already been resolved. #170</li> <li>Fix a bug that bare version specifiers in Poetry project can't be converted correctly. #172</li> <li>Fix the build error that destination directory is not created automatically. #173</li> </ul>"},{"location":"dev/changelog/#release-v0102-2020-11-05","title":"Release v0.10.2 (2020-11-05)","text":""},{"location":"dev/changelog/#bug-fixes_135","title":"Bug Fixes","text":"<ul> <li>Building editable distribution does not install <code>build-system.requires</code> anymore. #167</li> </ul>"},{"location":"dev/changelog/#release-v0101-2020-11-04","title":"Release v0.10.1 (2020-11-04)","text":""},{"location":"dev/changelog/#bug-fixes_136","title":"Bug Fixes","text":"<ul> <li>Switch the PEP 517 build frontend from <code>build</code> to a home-grown version. #162</li> <li>Synchronize the output of <code>LogWrapper</code>. #164</li> <li>Fix a bug that <code>is_subset</code> and <code>is_superset</code> may return wrong result when wildcard excludes overlaps with the upper bound. #165</li> </ul>"},{"location":"dev/changelog/#release-v0100-2020-10-20","title":"Release v0.10.0 (2020-10-20)","text":""},{"location":"dev/changelog/#features-improvements_81","title":"Features &amp; Improvements","text":"<ul> <li>Change to Git style config command. #157</li> <li>Add a command to generate scripts for autocompletion, which is backed by <code>pycomplete</code>. #159</li> </ul>"},{"location":"dev/changelog/#bug-fixes_137","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>sitecustomize.py</code> incorrectly gets injected into the editable console scripts. #158</li> </ul>"},{"location":"dev/changelog/#release-v092-2020-10-13","title":"Release v0.9.2 (2020-10-13)","text":""},{"location":"dev/changelog/#features-improvements_82","title":"Features &amp; Improvements","text":"<ul> <li>Cache the built wheels to accelerate resolution and installation process. #153</li> </ul>"},{"location":"dev/changelog/#bug-fixes_138","title":"Bug Fixes","text":"<ul> <li>Fix a bug that no wheel is matched when finding candidates to install. #155</li> <li>Fix a bug that installation in parallel will cause encoding initialization error on Ubuntu. #156</li> </ul>"},{"location":"dev/changelog/#release-v091-2020-10-13","title":"Release v0.9.1 (2020-10-13)","text":""},{"location":"dev/changelog/#features-improvements_83","title":"Features &amp; Improvements","text":"<ul> <li>Display plain text instead of spinner bar under verbose mode. #150</li> </ul>"},{"location":"dev/changelog/#bug-fixes_139","title":"Bug Fixes","text":"<ul> <li>Fix a bug that the result of <code>find_matched()</code> is exhausted when accessed twice. #149</li> </ul>"},{"location":"dev/changelog/#release-v090-2020-10-08","title":"Release v0.9.0 (2020-10-08)","text":""},{"location":"dev/changelog/#features-improvements_84","title":"Features &amp; Improvements","text":"<ul> <li>Allow users to combine several dependency sections to form an extra require. #131</li> <li>Split the PEP 517 backend to its own(battery included) package. #134</li> <li>Add a new option to list command to show reverse dependency graph. #137</li> </ul>"},{"location":"dev/changelog/#bug-fixes_140","title":"Bug Fixes","text":"<ul> <li>Fix a bug that spaces in path causes requirement parsing error. #138</li> <li>Fix a bug that requirement's python constraint is not respected when resolving. #141</li> </ul>"},{"location":"dev/changelog/#dependencies_22","title":"Dependencies","text":"<ul> <li>Update <code>pdm-pep517</code> to <code>0.2.0</code> that supports reading version from SCM. #146</li> </ul>"},{"location":"dev/changelog/#miscellany_18","title":"Miscellany","text":"<ul> <li>Add Python 3.9 to the CI version matrix to verify. #144</li> </ul>"},{"location":"dev/changelog/#release-v087-2020-09-04","title":"Release v0.8.7 (2020-09-04)","text":""},{"location":"dev/changelog/#bug-fixes_141","title":"Bug Fixes","text":"<ul> <li>Fix a compatibility issue with <code>wheel==0.35</code>. #135</li> </ul>"},{"location":"dev/changelog/#release-v086-2020-07-09","title":"Release v0.8.6 (2020-07-09)","text":""},{"location":"dev/changelog/#bug-fixes_142","title":"Bug Fixes","text":"<ul> <li>Fix a bug that extra sources are not respected when fetching distributions. #127</li> </ul>"},{"location":"dev/changelog/#release-v085-2020-06-24","title":"Release v0.8.5 (2020-06-24)","text":""},{"location":"dev/changelog/#bug-fixes_143","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>pdm export</code> fails when the project doesn't have <code>name</code> property. #126</li> </ul>"},{"location":"dev/changelog/#dependencies_23","title":"Dependencies","text":"<ul> <li>Upgrade dependency <code>pip</code> to <code>20.1</code>. #125</li> </ul>"},{"location":"dev/changelog/#release-v084-2020-05-21","title":"Release v0.8.4 (2020-05-21)","text":""},{"location":"dev/changelog/#features-improvements_85","title":"Features &amp; Improvements","text":"<ul> <li>Add a new command <code>export</code> to export to alternative formats. #117</li> </ul>"},{"location":"dev/changelog/#miscellany_19","title":"Miscellany","text":"<ul> <li>Add Dockerfile and pushed to Docker Hub. #122</li> </ul>"},{"location":"dev/changelog/#release-v083-2020-05-15","title":"Release v0.8.3 (2020-05-15)","text":""},{"location":"dev/changelog/#bug-fixes_144","title":"Bug Fixes","text":"<ul> <li>Fix the version constraint parsing of wheel metadata. #120</li> </ul>"},{"location":"dev/changelog/#release-v082-2020-05-03","title":"Release v0.8.2 (2020-05-03)","text":""},{"location":"dev/changelog/#bug-fixes_145","title":"Bug Fixes","text":"<ul> <li>Update resolvers to <code>resolvelib</code> 0.4.0. #118</li> </ul>"},{"location":"dev/changelog/#release-v081-2020-04-22","title":"Release v0.8.1 (2020-04-22)","text":""},{"location":"dev/changelog/#dependencies_24","title":"Dependencies","text":"<ul> <li>Switch to upstream <code>resolvelib 0.3.0</code>. #116</li> </ul>"},{"location":"dev/changelog/#release-v080-2020-04-20","title":"Release v0.8.0 (2020-04-20)","text":""},{"location":"dev/changelog/#features-improvements_86","title":"Features &amp; Improvements","text":"<ul> <li>Add a new command to search for packages #111</li> <li>Add <code>show</code> command to show package metadata. #114</li> </ul>"},{"location":"dev/changelog/#bug-fixes_146","title":"Bug Fixes","text":"<ul> <li>Fix a bug that environment markers cannot be evaluated correctly if extras are connected with \"or\". #107</li> <li>Don't consult PyPI JSON API by default for package metadata. #112</li> <li>Eliminate backslashes in markers for TOML documents. #115</li> </ul>"},{"location":"dev/changelog/#release-v071-2020-04-13","title":"Release v0.7.1 (2020-04-13)","text":""},{"location":"dev/changelog/#bug-fixes_147","title":"Bug Fixes","text":"<ul> <li>Editable packages requires <code>setuptools</code> to be installed in the isolated environment.</li> </ul>"},{"location":"dev/changelog/#release-v070-2020-04-12","title":"Release v0.7.0 (2020-04-12)","text":""},{"location":"dev/changelog/#features-improvements_87","title":"Features &amp; Improvements","text":"<ul> <li>Disable loading of site-packages under PEP 582 mode. #100</li> </ul>"},{"location":"dev/changelog/#bug-fixes_148","title":"Bug Fixes","text":"<ul> <li>Fix a bug that TOML parsing error is not correctly captured. #101</li> <li>Fix a bug of building wheels with C extensions that the platform in file name is incorrect. #99</li> </ul>"},{"location":"dev/changelog/#release-v065-2020-04-07","title":"Release v0.6.5 (2020-04-07)","text":""},{"location":"dev/changelog/#bug-fixes_149","title":"Bug Fixes","text":"<ul> <li>Unix style executable script suffix is missing.</li> </ul>"},{"location":"dev/changelog/#release-v064-2020-04-07","title":"Release v0.6.4 (2020-04-07)","text":""},{"location":"dev/changelog/#features-improvements_88","title":"Features &amp; Improvements","text":"<ul> <li>Update shebang lines in the executable scripts when doing <code>pdm use</code>. #96</li> <li>Auto-detect commonly used venv directories. #97</li> </ul>"},{"location":"dev/changelog/#release-v063-2020-03-30","title":"Release v0.6.3 (2020-03-30)","text":""},{"location":"dev/changelog/#bug-fixes_150","title":"Bug Fixes","text":"<ul> <li>Fix a bug of moving files across different file system. #95</li> </ul>"},{"location":"dev/changelog/#release-v062-2020-03-29","title":"Release v0.6.2 (2020-03-29)","text":""},{"location":"dev/changelog/#bug-fixes_151","title":"Bug Fixes","text":"<ul> <li>Validate user input for <code>python_requires</code> when initializing project. #89</li> <li>Ensure <code>wheel</code> package is available before building packages. #90</li> <li>Fix an issue of remove command that will unexpectedly uninstall packages in default section. #92</li> </ul>"},{"location":"dev/changelog/#dependencies_25","title":"Dependencies","text":"<ul> <li>Update dependencies <code>pythonfinder</code>, <code>python-cfonts</code>, <code>pip-shims</code> and many others.   Drop dependency <code>vistir</code>. #89</li> </ul>"},{"location":"dev/changelog/#release-v061-2020-03-25","title":"Release v0.6.1 (2020-03-25)","text":""},{"location":"dev/changelog/#features-improvements_89","title":"Features &amp; Improvements","text":"<ul> <li>Redirect output messages to log file for installation and locking. #84</li> </ul>"},{"location":"dev/changelog/#bug-fixes_152","title":"Bug Fixes","text":"<ul> <li>Fix a bug that parallel installation fails due to setuptools reinstalling. #83</li> </ul>"},{"location":"dev/changelog/#release-v060-2020-03-20","title":"Release v0.6.0 (2020-03-20)","text":""},{"location":"dev/changelog/#features-improvements_90","title":"Features &amp; Improvements","text":"<ul> <li>Support specifying build script for C extensions. #23</li> <li>Add test cases for <code>pdm build</code>. #81</li> <li>Make it configurable whether to consult PyPI JSON API since it may be not trustable.</li> <li>Support parallel installation.</li> <li>Add new command <code>pmd import</code> to import project metadata from <code>Pipfile</code>, <code>poetry</code>, <code>flit</code>, <code>requirements.txt</code>.   #79</li> <li><code>pdm init</code> and <code>pdm install</code> will auto-detect possible files that can be imported.</li> </ul>"},{"location":"dev/changelog/#bug-fixes_153","title":"Bug Fixes","text":"<ul> <li>Fix wheel builds when <code>package_dir</code> is mapped. #81</li> <li><code>pdm init</code> will use the current directory rather than finding the parents when global project is not activated.</li> </ul>"},{"location":"dev/changelog/#release-v050-2020-03-14","title":"Release v0.5.0 (2020-03-14)","text":""},{"location":"dev/changelog/#features-improvements_91","title":"Features &amp; Improvements","text":"<ul> <li>Introduce a super easy-to-extend plug-in system to PDM. #75</li> </ul>"},{"location":"dev/changelog/#improved-documentation_15","title":"Improved Documentation","text":"<ul> <li>Documentation on how to write a plugin. #75</li> </ul>"},{"location":"dev/changelog/#bug-fixes_154","title":"Bug Fixes","text":"<ul> <li>Fix a typo in metadata parsing from <code>plugins</code> to <code>entry_points</code></li> </ul>"},{"location":"dev/changelog/#release-v042-2020-03-13","title":"Release v0.4.2 (2020-03-13)","text":""},{"location":"dev/changelog/#features-improvements_92","title":"Features &amp; Improvements","text":"<ul> <li>Refactor the CLI part, switch from <code>click</code> to <code>argparse</code>, for better extensibility. #73</li> <li>Allow users to configure to install packages into venv when it is activated. #74</li> </ul>"},{"location":"dev/changelog/#release-v041-2020-03-11","title":"Release v0.4.1 (2020-03-11)","text":""},{"location":"dev/changelog/#features-improvements_93","title":"Features &amp; Improvements","text":"<ul> <li>Add a minimal dependency set for global project. #72</li> </ul>"},{"location":"dev/changelog/#release-v040-2020-03-10","title":"Release v0.4.0 (2020-03-10)","text":""},{"location":"dev/changelog/#features-improvements_94","title":"Features &amp; Improvements","text":"<ul> <li>Global project support</li> <li>Add a new option <code>-g/--global</code> to manage global project. The default location is at <code>~/.pdm/global-project</code>.</li> <li>Use the virtualenv interpreter when detected inside an activated venv.</li> <li>Add a new option <code>-p/--project</code> to select project root other than the default one. #30</li> <li>Add a new command <code>pdm config del</code> to delete an existing config item. #71</li> </ul>"},{"location":"dev/changelog/#bug-fixes_155","title":"Bug Fixes","text":"<ul> <li>Fix a URL parsing issue that username will be dropped in the SSH URL. #68</li> </ul>"},{"location":"dev/changelog/#improved-documentation_16","title":"Improved Documentation","text":"<ul> <li>Add docs for global project and selecting project path. #30</li> </ul>"},{"location":"dev/changelog/#release-v032-2020-03-08","title":"Release v0.3.2 (2020-03-08)","text":""},{"location":"dev/changelog/#features-improvements_95","title":"Features &amp; Improvements","text":"<ul> <li>Display all available Python interpreters if users don't give one in <code>pdm init</code>. #67</li> </ul>"},{"location":"dev/changelog/#bug-fixes_156","title":"Bug Fixes","text":"<ul> <li>Regard <code>4.0</code> as infinite upper bound when checking subsetting. #66</li> </ul>"},{"location":"dev/changelog/#release-v031-2020-03-07","title":"Release v0.3.1 (2020-03-07)","text":""},{"location":"dev/changelog/#bug-fixes_157","title":"Bug Fixes","text":"<ul> <li>Fix a bug that <code>ImpossiblePySpec</code>'s hash clashes with normal one.</li> </ul>"},{"location":"dev/changelog/#release-v030-2020-02-28","title":"Release v0.3.0 (2020-02-28)","text":""},{"location":"dev/changelog/#features-improvements_96","title":"Features &amp; Improvements","text":"<ul> <li>Add a new command <code>pdm config</code> to inspect configurations. #26</li> <li>Add a new command <code>pdm cache clear</code> to clean caches. #63</li> </ul>"},{"location":"dev/changelog/#bug-fixes_158","title":"Bug Fixes","text":"<ul> <li>Correctly show dependency graph when circular dependencies exist. #62</li> </ul>"},{"location":"dev/changelog/#improved-documentation_17","title":"Improved Documentation","text":"<ul> <li>Write the initial documentation for PDM. #14</li> </ul>"},{"location":"dev/changelog/#release-v026-2020-02-25","title":"Release v0.2.6 (2020-02-25)","text":""},{"location":"dev/changelog/#features-improvements_97","title":"Features &amp; Improvements","text":"<ul> <li>Improve the user interface of selecting Python interpreter. #54</li> </ul>"},{"location":"dev/changelog/#bug-fixes_159","title":"Bug Fixes","text":"<ul> <li>Fix the wheel installer to correctly unparse the flags of console scripts. #56</li> <li>Fix a bug that OS-dependent hashes are not saved. #57</li> </ul>"},{"location":"dev/changelog/#release-v025-2020-02-22","title":"Release v0.2.5 (2020-02-22)","text":""},{"location":"dev/changelog/#features-improvements_98","title":"Features &amp; Improvements","text":"<ul> <li>Allow specifying Python interpreter via <code>--python</code> option in <code>pdm init</code>. #49</li> <li>Set <code>python_requires</code> when initializing and defaults to <code>&gt;={current_version}</code>. #50</li> </ul>"},{"location":"dev/changelog/#bug-fixes_160","title":"Bug Fixes","text":"<ul> <li>Always consider wheels before tarballs; correctly merge markers from different parents. #47</li> <li>Filter out incompatible wheels when installing. #48</li> </ul>"},{"location":"dev/changelog/#release-v024-2020-02-21","title":"Release v0.2.4 (2020-02-21)","text":""},{"location":"dev/changelog/#bug-fixes_161","title":"Bug Fixes","text":"<ul> <li>Use the project local interpreter to build wheels. #43</li> <li>Correctly merge Python specifiers when possible. #4</li> </ul>"},{"location":"dev/changelog/#release-v023-2020-02-21","title":"Release v0.2.3 (2020-02-21)","text":""},{"location":"dev/changelog/#bug-fixes_162","title":"Bug Fixes","text":"<ul> <li>Fix a bug that editable build generates a malformed <code>setup.py</code>.</li> </ul>"},{"location":"dev/changelog/#release-v022-2020-02-20","title":"Release v0.2.2 (2020-02-20)","text":""},{"location":"dev/changelog/#features-improvements_99","title":"Features &amp; Improvements","text":"<ul> <li>Add a fancy greeting banner when user types <code>pdm --help</code>. #42</li> </ul>"},{"location":"dev/changelog/#bug-fixes_163","title":"Bug Fixes","text":"<ul> <li>Fix the RECORD file in built wheel. #41</li> </ul>"},{"location":"dev/changelog/#dependencies_26","title":"Dependencies","text":"<ul> <li>Add dependency <code>python-cfonts</code> to display banner. #42</li> </ul>"},{"location":"dev/changelog/#release-v021-2020-02-18","title":"Release v0.2.1 (2020-02-18)","text":""},{"location":"dev/changelog/#bug-fixes_164","title":"Bug Fixes","text":"<ul> <li>Fix a bug that short python_version markers can't be parsed correctly. #38</li> <li>Make <code>_editable_intall.py</code> compatible with Py2.</li> </ul>"},{"location":"dev/changelog/#release-v020-2020-02-14","title":"Release v0.2.0 (2020-02-14)","text":""},{"location":"dev/changelog/#features-improvements_100","title":"Features &amp; Improvements","text":"<ul> <li>New option: <code>pdm list --graph</code> to show a dependency graph of the working set. #10</li> <li>New option: <code>pdm update --unconstrained</code> to ignore the version constraint of given packages. #13</li> <li>Improve the error message when project is not initialized before running commands. #19</li> <li>Pinned candidates in lock file are reused when relocking during <code>pdm install</code>. #33</li> <li>Use the pyenv interpreter value if pyenv is installed. #36</li> <li>Introduce a new command <code>pdm info</code> to show project environment information. #9</li> </ul>"},{"location":"dev/changelog/#bug-fixes_165","title":"Bug Fixes","text":"<ul> <li>Fix a bug that candidate hashes will be lost when reused. #11</li> </ul>"},{"location":"dev/changelog/#dependencies_27","title":"Dependencies","text":"<ul> <li>Update <code>pip</code> to <code>20.0</code>, update <code>pip_shims</code> to <code>0.5.0</code>. #28</li> </ul>"},{"location":"dev/changelog/#miscellany_20","title":"Miscellany","text":"<ul> <li>Add a script named <code>setup_dev.py</code> for the convenience to setup pdm for development. #29</li> </ul>"},{"location":"dev/changelog/#release-v012-2020-02-09","title":"Release v0.1.2 (2020-02-09)","text":""},{"location":"dev/changelog/#features","title":"Features","text":"<ul> <li>New command pdm use to switch python versions. #8</li> <li>New option pdm list --graph to show a dependency graph. #10</li> <li>Read metadata from lockfile when pinned candidate is reused.</li> </ul>"},{"location":"dev/changelog/#release-v011-2020-02-07","title":"Release v0.1.1 (2020-02-07)","text":""},{"location":"dev/changelog/#features_1","title":"Features","text":"<ul> <li>Get version from the specified file. #6</li> <li>Add column header to pdm list output.</li> </ul>"},{"location":"dev/changelog/#release-v010-2020-02-07","title":"Release v0.1.0 (2020-02-07)","text":""},{"location":"dev/changelog/#bugfixes","title":"Bugfixes","text":"<ul> <li>Pass exit code to parent process in pdm run.</li> <li>Fix error handling for CLI. #19</li> </ul>"},{"location":"dev/changelog/#miscellany_21","title":"Miscellany","text":"<ul> <li>Refactor the installer mocking for tests.</li> </ul>"},{"location":"dev/changelog/#release-v005-2020-01-22","title":"Release v0.0.5 (2020-01-22)","text":""},{"location":"dev/changelog/#improvements","title":"Improvements","text":"<ul> <li>Ensure pypi index url is fetched in addition to the source settings. #3</li> </ul>"},{"location":"dev/changelog/#bugfixes_1","title":"Bugfixes","text":"<ul> <li>Fix an issue that leading \"c\"s are mistakenly stripped. #5</li> <li>Fix an error with PEP 517 building.</li> </ul>"},{"location":"dev/changelog/#release-v004-2020-01-22","title":"Release v0.0.4 (2020-01-22)","text":""},{"location":"dev/changelog/#improvements_1","title":"Improvements","text":"<ul> <li>Fix editable installation, now editable scripts can also be executed from outside!</li> <li>Content hash is calculated based on dependencies and sources, not other metadata.</li> </ul>"},{"location":"dev/changelog/#bugfixes_2","title":"Bugfixes","text":"<ul> <li>Fix an issue that editable distributions can not be removed.</li> </ul>"},{"location":"dev/changelog/#release-v003-2020-01-22","title":"Release v0.0.3 (2020-01-22)","text":""},{"location":"dev/changelog/#features_2","title":"Features","text":"<ul> <li>Add <code>pdm init</code> to bootstrap a project.</li> </ul>"},{"location":"dev/changelog/#release-v002-2020-01-22","title":"Release v0.0.2 (2020-01-22)","text":""},{"location":"dev/changelog/#features_3","title":"Features","text":"<ul> <li>A complete functioning PEP 517 build backend.</li> <li><code>pdm build</code> command.</li> </ul>"},{"location":"dev/changelog/#miscellany_22","title":"Miscellany","text":"<ul> <li>Add a Chinese README</li> </ul>"},{"location":"dev/changelog/#features_4","title":"Features","text":"<ul> <li>Add <code>pdm init</code> to bootstrap a project.</li> </ul>"},{"location":"dev/changelog/#release-v001-2020-01-20","title":"Release v0.0.1 (2020-01-20)","text":""},{"location":"dev/changelog/#features_5","title":"Features","text":"<ul> <li>A dependency resolver that just works.</li> <li>A PEP 582 installer.</li> <li>PEP 440 version specifiers.</li> <li>PEP 508 environment markers.</li> <li>Running scripts with PEP 582 local packages.</li> <li>Console scripts are injected with local paths.</li> <li>A neat CLI.</li> <li>add, lock, list, update, remove commands.</li> <li>PEP 517 build backends.</li> <li>Continuous Integration.</li> </ul>"},{"location":"dev/contributing/","title":"Contributing to PDM","text":"<p>First off, thanks for taking the time to contribute! Contributions include but are not restricted to:</p> <ul> <li>Reporting bugs</li> <li>Contributing to code</li> <li>Writing tests</li> <li>Writing documentation</li> </ul> <p>The following is a set of guidelines for contributing.</p>"},{"location":"dev/contributing/#a-recommended-flow-of-contributing-to-an-open-source-project","title":"A recommended flow of contributing to an Open Source project","text":"<p>This section is for beginners to OSS. If you are an experienced OSS developer, you can skip this section.</p> <ol> <li>First, fork this project to your own namespace using the fork button at the top right of the repository page.</li> <li>Clone the upstream repository to local:    <pre><code>git clone https://github.com/pdm-project/pdm.git\n# Or if you prefer SSH clone:\ngit clone git@github.com:pdm-project/pdm.git\n</code></pre></li> <li>Add the fork as a new remote:    <pre><code>git remote add fork https://github.com/yourname/pdm.git\ngit fetch fork\n</code></pre>    where <code>fork</code> is the remote name of the fork repository.</li> </ol> <p>ProTips:</p> <ol> <li>Don't modify code on the main branch, the main branch should always keep track of origin/main.</li> </ol> <p>To update main branch to date:</p> <pre><code>git pull origin main\n# In rare cases that your local main branch diverges from the remote main:\ngit fetch origin &amp;&amp; git reset --hard main\n</code></pre> <ol> <li>Create a new branch based on the up-to-date main branch for new patches.</li> <li>Create a Pull Request from that patch branch.</li> </ol>"},{"location":"dev/contributing/#local-development","title":"Local development","text":"<p>We recommend working in a virtual environment. Feel free to create a virtual environment with either the <code>venv</code> module or the <code>virtualenv</code> tool. For example:</p> <pre><code>python -m venv .venv\n. .venv/bin/activate  # linux\n.venv/Scripts/activate  # windows\n</code></pre> <p>Make sure your <code>pip</code> is newer than <code>21.3</code> to install PDM in develop/editable mode.</p> <pre><code>python -m pip install -U \"pip&gt;=21.3\"\npython -m pip install -e .\n</code></pre> <p>Make sure PDM uses the virtual environment you just created:</p> <pre><code>pdm config -l python.use_venv true\npdm config -l venv.in_project true\n</code></pre> <p>Install PDM development dependencies:</p> <pre><code>pdm install\n</code></pre> <p>Now, all dependencies are installed into the Python environment you chose, which will be used for development after this point.</p>"},{"location":"dev/contributing/#run-tests","title":"Run tests","text":"<pre><code>pdm run test\n</code></pre> <p>The test suite is still simple and needs expansion! Please help write more test cases.</p> <p>Note</p> <p>You can also run your test suite against all supported Python version using <code>tox</code> with the <code>tox-pdm</code> plugin. You can either run it by yourself with:</p> <pre><code>tox\n</code></pre> <p>or from <code>pdm</code> with:</p> <pre><code>pdm run tox\n</code></pre>"},{"location":"dev/contributing/#code-style","title":"Code style","text":"<p>PDM uses <code>pre-commit</code> for linting. Install <code>pre-commit</code> first, for example with pip or pipx:</p> <pre><code>python -m pip install pre-commit\n</code></pre> <pre><code>pipx install pre-commit\n</code></pre> <p>Then initialize <code>pre-commit</code>:</p> <pre><code>pre-commit install\n</code></pre> <p>You can now lint the code with:</p> <pre><code>pdm run lint\n</code></pre> <p>PDM uses <code>black</code> for code style and <code>isort</code> for sorting import statements. If you are not following them, the CI will fail and your Pull Request will not be merged.</p>"},{"location":"dev/contributing/#news-fragments","title":"News fragments","text":"<p>When you make changes such as fixing a bug or adding a feature, you must add a news fragment describing your change. News fragments are placed in the <code>news/</code> directory, and should be named according to this pattern: <code>&lt;issue_num&gt;.&lt;issue_type&gt;.md</code> (e.g., <code>566.bugfix.md</code>).</p>"},{"location":"dev/contributing/#issue-types","title":"Issue Types","text":"<ul> <li><code>feature</code>: Features and improvements</li> <li><code>bugfix</code>: Bug fixes</li> <li><code>refactor</code>: Code restructures</li> <li><code>doc</code>: Added or improved documentation</li> <li><code>dep</code>: Changes to dependencies</li> <li><code>removal</code>: Removals or deprecations in the API</li> <li><code>misc</code>: Miscellaneous changes that don't fit any of the other categories</li> </ul> <p>The contents of the file should be a single sentence in the imperative mood that describes your changes. (e.g., <code>Deduplicate the plugins list.</code> ) See entries in the Change Log for more examples.</p>"},{"location":"dev/contributing/#preview-the-documentation","title":"Preview the documentation","text":"<p>If you make some changes to the <code>docs/</code> and you want to preview the build result, simply do:</p> <pre><code>pdm run doc\n</code></pre>"},{"location":"dev/contributing/#release","title":"Release","text":"<p>Once all changes are done and ready to release, you can preview the changelog contents by running:</p> <pre><code>pdm run release --dry-run\n</code></pre> <p>Make sure the next version and the changelog are as expected in the output.</p> <p>Then cut a release on the main branch:</p> <pre><code>pdm run release\n</code></pre> <p>GitHub action will create the release and upload the distributions to PyPI.</p> <p>Read more options about version bumping by <code>pdm run release --help</code>.</p>"},{"location":"dev/fixtures/","title":"Pytest fixtures","text":"<p>Some reusable fixtures for <code>pytest</code>.</p> <p>+++ 2.4.0</p> <p>To enable them in your test, add <code>pdm.pytest</code> as a plugin. You can do so in your root <code>conftest.py</code>:</p> conftest.py<pre><code># single plugin\npytest_plugins = \"pytest.plugin\"\n\n# many plugins\npytest_plugins = [\n    ...\n    \"pdm.pytest\",\n    ...\n]\n</code></pre>"},{"location":"dev/fixtures/#pdm.pytest.IndexMap","title":"<code>IndexMap = Dict[str, Path]</code>  <code>module-attribute</code>","text":"<p>Path some root-relative http paths to some local paths</p>"},{"location":"dev/fixtures/#pdm.pytest.IndexOverrides","title":"<code>IndexOverrides = Dict[str, bytes]</code>  <code>module-attribute</code>","text":"<p>PyPI indexes overrides fixture format</p>"},{"location":"dev/fixtures/#pdm.pytest.IndexesDefinition","title":"<code>IndexesDefinition = Dict[str, Union[Tuple[IndexMap, IndexOverrides, bool], IndexMap]]</code>  <code>module-attribute</code>","text":"<p>Mock PyPI indexes format</p>"},{"location":"dev/fixtures/#pdm.pytest.Distribution","title":"<code>Distribution</code>","text":"<p>A mock Distribution</p>"},{"location":"dev/fixtures/#pdm.pytest.LocalIndexTransport","title":"<code>LocalIndexTransport</code>","text":"<p>         Bases: <code>httpx.BaseTransport</code></p> <p>A local file transport for HTTPX.</p> <p>Allows to mock some HTTP requests with some local files</p>"},{"location":"dev/fixtures/#pdm.pytest.MockWorkingSet","title":"<code>MockWorkingSet</code>","text":"<p>         Bases: <code>collections.abc.MutableMapping</code></p> <p>A mock working set</p>"},{"location":"dev/fixtures/#pdm.pytest.PDMCallable","title":"<code>PDMCallable</code>","text":"<p>         Bases: <code>Protocol</code></p> <p>The PDM fixture callable signature</p>"},{"location":"dev/fixtures/#pdm.pytest.PDMCallable.__call__","title":"<code>__call__(args, strict=False, input=None, obj=None, env=None, **kwargs)</code>","text":"<p>Parameters:</p> Name Type Description Default <code>args</code> <code>str | list[str]</code> <p>the command arguments as a single lexable string or a strings array</p> required <code>strict</code> <code>bool</code> <p>raise an exception on failure instead of returning if enabled</p> <code>False</code> <code>input</code> <code>str | None</code> <p>an optional string to be submitted too <code>stdin</code></p> <code>None</code> <code>obj</code> <code>Project | None</code> <p>an optional existing <code>Project</code>.</p> <code>None</code> <code>env</code> <code>Mapping[str, str] | None</code> <p>override the environment variables with those</p> <code>None</code> <p>Returns:</p> Type Description <code>RunResult</code> <p>The command result</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult","title":"<code>RunResult</code>  <code>dataclass</code>","text":"<p>Store a command execution result.</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.exception","title":"<code>exception: Exception | None = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":"<p>If set, the exception raised on execution</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.exit_code","title":"<code>exit_code: int</code>  <code>instance-attribute</code>","text":"<p>The execution exit code</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.output","title":"<code>output: str</code>  <code>property</code>","text":"<p>The execution <code>stdout</code> output (<code>stdout</code> alias)</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.outputs","title":"<code>outputs: str</code>  <code>property</code>","text":"<p>The execution <code>stdout</code> and <code>stderr</code> outputs concatenated</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.stderr","title":"<code>stderr: str</code>  <code>instance-attribute</code>","text":"<p>The execution <code>stderr</code> output</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.stdout","title":"<code>stdout: str</code>  <code>instance-attribute</code>","text":"<p>The execution <code>stdout</code> output</p>"},{"location":"dev/fixtures/#pdm.pytest.RunResult.print","title":"<code>print()</code>","text":"<p>A debugging facility</p>"},{"location":"dev/fixtures/#pdm.pytest.TestRepository","title":"<code>TestRepository</code>","text":"<p>         Bases: <code>BaseRepository</code></p> <p>A mock repository to ease testing dependencies</p>"},{"location":"dev/fixtures/#pdm.pytest.build_env","title":"<code>build_env(build_env_wheels, tmp_path_factory)</code>","text":"<p>A fixture build environment</p> <p>Parameters:</p> Name Type Description Default <code>build_env_wheels</code> <code>Iterable[Path]</code> <p>a list of wheel to install in the environment</p> required <p>Returns:</p> Type Description <code>Path</code> <p>The build environment temporary path</p>"},{"location":"dev/fixtures/#pdm.pytest.build_env_wheels","title":"<code>build_env_wheels()</code>","text":"<p>Expose some wheels to be installed in the build environment.</p> <p>Override to provide your owns.</p> <p>Returns:</p> Type Description <code>Iterable[Path]</code> <p>a list of wheels paths to install</p>"},{"location":"dev/fixtures/#pdm.pytest.local_finder_artifacts","title":"<code>local_finder_artifacts()</code>","text":"<p>The local finder search path as a fixture</p> <p>Override to provides your own artifacts.</p> <p>Returns:</p> Type Description <code>Path</code> <p>The path to the artifacts root</p>"},{"location":"dev/fixtures/#pdm.pytest.pdm","title":"<code>pdm(core, monkeypatch)</code>","text":"<p>A fixture allowing to execute PDM commands</p> <p>Returns:</p> Type Description <code>PDMCallable</code> <p>A <code>pdm</code> fixture command.</p>"},{"location":"dev/fixtures/#pdm.pytest.project","title":"<code>project(project_no_init)</code>","text":"<p>A fixture creating an initialized test project for the current test.</p> <p>Returns:</p> Type Description <code>Project</code> <p>The initialized project</p>"},{"location":"dev/fixtures/#pdm.pytest.project_no_init","title":"<code>project_no_init(tmp_path, mocker, core, build_test_session, monkeypatch, build_env)</code>","text":"<p>A fixture creating a non-initialized test project for the current test.</p> <p>Returns:</p> Type Description <code>Project</code> <p>The non-initialized project</p>"},{"location":"dev/fixtures/#pdm.pytest.pypi_indexes","title":"<code>pypi_indexes()</code>","text":"<p>Provides some mocked PyPI entries</p> <p>Returns:</p> Type Description <code>IndexesDefinition</code> <p>a definition of the mocked indexes</p>"},{"location":"dev/fixtures/#pdm.pytest.remove_pep582_path_from_pythonpath","title":"<code>remove_pep582_path_from_pythonpath(pythonpath)</code>","text":"<p>Remove all pep582 paths of PDM from PYTHONPATH</p>"},{"location":"dev/fixtures/#pdm.pytest.repository","title":"<code>repository(project, mocker, repository_pypi_json, local_finder)</code>","text":"<p>A fixture providing a mock PyPI repository</p> <p>Returns:</p> Type Description <code>TestRepository</code> <p>A mock repository</p>"},{"location":"dev/fixtures/#pdm.pytest.repository_pypi_json","title":"<code>repository_pypi_json()</code>","text":"<p>The test repository fake PyPI definition path as a fixture</p> <p>Override to provides your own definition path.</p> <p>Returns:</p> Type Description <code>Path</code> <p>The path to a fake PyPI repository JSON definition</p>"},{"location":"dev/fixtures/#pdm.pytest.venv_backends","title":"<code>venv_backends(project, request)</code>","text":"<p>A fixture iterating over <code>venv</code> backends</p>"},{"location":"dev/fixtures/#pdm.pytest.working_set","title":"<code>working_set(mocker, repository)</code>","text":"<p>a mock working set as a fixture</p> <p>Returns:</p> Type Description <code>MockWorkingSet</code> <p>a mock working set</p>"},{"location":"dev/write/","title":"PDM Plugins","text":"<p>PDM is aiming at being a community driven package manager. It is shipped with a full-featured plug-in system, with which you can:</p> <ul> <li>Develop a new command for PDM</li> <li>Add additional options to existing PDM commands</li> <li>Change PDM's behavior by reading additional config items</li> <li>Control the process of dependency resolution or installation</li> </ul>"},{"location":"dev/write/#what-should-a-plugin-do","title":"What should a plugin do","text":"<p>The core PDM project focuses on dependency management and package publishing. Other functionalities you wish to integrate with PDM are preferred to lie in their own plugins and released as standalone PyPI projects. In case the plugin is considered a good supplement of the core project it may have a chance to be absorbed into PDM.</p>"},{"location":"dev/write/#write-your-own-plugin","title":"Write your own plugin","text":"<p>In the following sections, I will show an example of adding a new command <code>hello</code> which reads the <code>hello.name</code> config.</p>"},{"location":"dev/write/#write-the-command","title":"Write the command","text":"<p>The PDM's CLI module is designed in a way that user can easily \"inherit and modify\". To write a new command:</p> <pre><code>from pdm.cli.commands.base import BaseCommand\n\nclass HelloCommand(BaseCommand):\n\"\"\"Say hello to the specified person.\n    If none is given, will read from \"hello.name\" config.\n    \"\"\"\n\n    def add_arguments(self, parser):\n        parser.add_argument(\"-n\", \"--name\", help=\"the person's name to whom you greet\")\n\n    def handle(self, project, options):\n        if not options.name:\n            name = project.config[\"hello.name\"]\n        else:\n            name = options.name\n        print(f\"Hello, {name}\")\n</code></pre> <p>First, let's create a new <code>HelloCommand</code> class inheriting from <code>pdm.cli.commands.base.BaseCommand</code>. It has two major functions:</p> <ul> <li><code>add_arguments()</code> to manipulate the argument parser passed as the only argument,   where you can add additional command line arguments to it</li> <li><code>handle()</code> to do something when the subcommand is matched, you can do nothing by writing a single <code>pass</code> statement.   It accepts two arguments: an <code>pdm.project.Project</code> object as the first one and the parsed <code>argparse.Namespace</code> object as the second.</li> </ul> <p>The document string will serve as the command help text, which will be shown in <code>pdm --help</code>.</p> <p>Besides, PDM's subcommand has two default options: <code>-v/--verbose</code> to change the verbosity level and <code>-g/--global</code> to enable global project. If you don't want these default options, override the <code>arguments</code> class attribute to a list of <code>pdm.cli.options.Option</code> objects, or assign it to an empty list to have no default options:</p> <pre><code>class HelloCommand(BaseCommand):\n\narguments = []\n</code></pre> <p>Note</p> <p>The default options are loaded first, then <code>add_arguments()</code> is called.</p>"},{"location":"dev/write/#register-the-command-to-the-core-object","title":"Register the command to the core object","text":"<p>Write a function somewhere in your plugin project. There is no limit on what the name of the function is, but the function should take only one argument -- the PDM core object:</p> <pre><code>def hello_plugin(core):\ncore.register_command(HelloCommand, \"hello\")\n</code></pre> <p>Call <code>core.register_command()</code> to register the command. The second argument as the name of the subcommand is optional. PDM will look for the <code>HelloCommand</code>'s <code>name</code> attribute if the name is not passed.</p>"},{"location":"dev/write/#add-a-new-config-item","title":"Add a new config item","text":"<p>Let's recall the first code snippet, <code>hello.name</code> config key is consulted for the name if not passed via the command line.</p> <pre><code>class HelloCommand(BaseCommand):\n\"\"\"Say hello to the specified person.\n    If none is given, will read from \"hello.name\" config.\n    \"\"\"\n\n    def add_arguments(self, parser):\n        parser.add_argument(\"-n\", \"--name\", help=\"the person's name to whom you greet\")\n\n    def handle(self, project, options):\n        if not options.name:\nname = project.config[\"hello.name\"]\nelse:\n            name = options.name\n        print(f\"Hello, {name}\")\n</code></pre> <p>Till now, if you query the config value by <code>pdm config get hello.name</code>, an error will pop up saying it is not a valid config key. You need to register the config item, too:</p> <pre><code>from pdm.project.config import ConfigItem\n\ndef hello_plugin(core):\n    core.register_command(HelloCommand, \"hello\")\ncore.add_config(\"hello.name\", ConfigItem(\"The person's name\", \"John\"))\n</code></pre> <p>where <code>ConfigItem</code> class takes 4 parameters, in the following order:</p> <ul> <li><code>description</code>: a description of the config item</li> <li><code>default</code>: default value of the config item</li> <li><code>global_only</code>: whether the config is allowed to set in home config only</li> <li><code>env_var</code>: the name of environment variable which will be read as the config value</li> </ul>"},{"location":"dev/write/#other-plugin-points","title":"Other plugin points","text":"<p>Besides of commands and configurations, the <code>core</code> object exposes some other methods and attributes to override. PDM also provides some signals you can listen to. Please read the API reference for more details.</p>"},{"location":"dev/write/#tips-about-developing-a-pdm-plugin","title":"Tips about developing a PDM plugin","text":"<p>When developing a plugin, one hopes to activate and plugin in development and get updated when the code changes.</p> <p>You can achieve this by installing the plugin in editable mode. To do this, specify the dependencies in <code>tool.pdm.plugins</code> array:</p> <pre><code>[tool.pdm]\nplugins = [\n\"-e file:///${PROJECT_ROOT}\"\n]\n</code></pre> <p>Then install it with:</p> <pre><code>pdm install --plugins\n</code></pre> <p>After that, all the dependencies are available in a project plugin library, including the plugin itself, in editable mode. That means any change to the codebase will take effect immediately without re-installation. The <code>pdm</code> executable also uses a Python interpreter under the hood, so if you run <code>pdm</code> from inside the plugin project, the plugin in development will be activated automatically, and you can do some testing to see how it works.</p>"},{"location":"dev/write/#testing-your-plugin","title":"Testing your plugin","text":"<p>PDM exposes some pytest fixtures as a plugin in the <code>pdm.pytest</code> module. To benefit from them, you must add <code>pdm[pytest]</code> as a test dependency.</p> <p>To enable them in your test, add <code>pdm.pytest</code> as a plugin. You can do so by in your root <code>conftest.py</code>:</p> conftest.py<pre><code># single plugin\npytest_plugins = \"pytest.plugin\"\n\n# many plugins\npytest_plugins = [\n    ...\n    \"pdm.pytest\",\n    ...\n]\n</code></pre> <p>You can see some usage examples into PDM own tests, especially the conftest.py file for configuration.</p> <p>See the pytest fixtures documentation for more details.</p>"},{"location":"dev/write/#publish-your-plugin","title":"Publish your plugin","text":"<p>Now you have defined your plugin already, let's distribute it to PyPI. PDM's plugins are discovered by entry point types. Create an <code>pdm</code> entry point and point to your plugin callable (yeah, it doesn't need to be a function, any callable object can work):</p> <p>PEP 621:</p> <pre><code># pyproject.toml\n\n[project.entry-points.pdm]\nhello = \"my_plugin:hello_plugin\"\n</code></pre> <p>setuptools:</p> <pre><code># setup.py\n\nsetup(\n    ...\n    entry_points={\"pdm\": [\"hello = my_plugin:hello_plugin\"]}\n    ...\n)\n</code></pre>"},{"location":"dev/write/#activate-the-plugin","title":"Activate the plugin","text":"<p>As plugins are loaded via entry points, they can be activated with no more steps than just installing the plugin. For convenience, PDM provides a <code>plugin</code> command group to manage plugins.</p> <p>Assume your plugin is published as <code>pdm-hello</code>:</p> <pre><code>pdm self add pdm-hello\n</code></pre> <p>Now type <code>pdm --help</code> in the terminal, you will see the new added <code>hello</code> command and use it:</p> <pre><code>$ pdm hello Jack\nHello, Jack\n</code></pre> <p>See more plugin management subcommands by typing <code>pdm self --help</code> in the terminal.</p>"},{"location":"dev/write/#specify-the-plugins-in-project","title":"Specify the plugins in project","text":"<p>To specify the required plugins for a project, you can use the <code>tool.pdm.plugins</code> config in the <code>pyproject.toml</code> file. These dependencies can be installed into a project plugin library by running <code>pdm install --plugins</code>. The project plugin library will be loaded in subsequent PDM commands.</p> <p>This is useful when you want to share the same plugin set with the contributors.</p> <pre><code># pyproject.toml\n[tool.pdm]\nplugins = [\n\"pdm-packer\"\n]\n</code></pre> <p>Run <code>pdm install --plugins</code> to install and activate the plugins.</p> <p>Alternatively, you can have project-local plugins that are not published to PyPI, by using editable local dependencies:</p> <pre><code># pyproject.toml\n[tool.pdm]\nplugins = [\n\"-e file:///${PROJECT_ROOT}/plugins/my_plugin\"\n]\n</code></pre>"},{"location":"reference/api/","title":"API Reference","text":""},{"location":"reference/api/#pdm.core.Core","title":"<code>pdm.core.Core</code>","text":"<p>A high level object that manages all classes and configurations</p>"},{"location":"reference/api/#pdm.core.Core.state","title":"<code>state: State</code>  <code>property</code>","text":"<p>Get the current state object.</p>"},{"location":"reference/api/#pdm.core.Core.add_config","title":"<code>add_config(name, config_item)</code>  <code>staticmethod</code>","text":"<p>Add a config item to the configuration class.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name of the config item</p> required <code>config_item</code> <code>pdm.project.config.ConfigItem</code> <p>The config item to add</p> required"},{"location":"reference/api/#pdm.core.Core.create_project","title":"<code>create_project(root_path=None, is_global=False, global_config=None)</code>","text":"<p>Create a new project object</p> <p>Parameters:</p> Name Type Description Default <code>root_path</code> <code>PathLike</code> <p>The path to the project root directory</p> <code>None</code> <code>is_global</code> <code>bool</code> <p>Whether the project is a global project</p> <code>False</code> <code>global_config</code> <code>str</code> <p>The path to the global config file</p> <code>None</code> <p>Returns:</p> Type Description <code>Project</code> <p>The project object</p>"},{"location":"reference/api/#pdm.core.Core.handle","title":"<code>handle(project, options)</code>","text":"<p>Called before command invocation</p>"},{"location":"reference/api/#pdm.core.Core.load_plugins","title":"<code>load_plugins()</code>","text":"<p>Import and load plugins under <code>pdm.plugin</code> namespace A plugin is a callable that accepts the core object as the only argument.</p> Example <pre><code>def my_plugin(core: pdm.core.Core) -&gt; None:\n    ...\n</code></pre>"},{"location":"reference/api/#pdm.core.Core.main","title":"<code>main(args=None, prog_name=None, obj=None, **extra)</code>","text":"<p>The main entry function</p>"},{"location":"reference/api/#pdm.core.Core.push_state","title":"<code>push_state(__empty=False, /, **kwargs)</code>","text":"<p>Push a new state object to the stack.</p> <p>Parameters:</p> Name Type Description Default <code>__empty</code> <code>bool</code> <p>Whether to make an empty state.</p> <code>False</code> <code>**kwargs</code> <code>Any</code> <p>The new attributes to set to the state object.</p> <code>{}</code>"},{"location":"reference/api/#pdm.core.Core.register_command","title":"<code>register_command(command, name=None)</code>","text":"<p>Register a subcommand to the subparsers, with an optional name of the subcommand.</p> <p>Parameters:</p> Name Type Description Default <code>command</code> <code>Type[pdm.cli.commands.base.BaseCommand]</code> <p>The command class to register</p> required <code>name</code> <code>str</code> <p>The name of the subcommand, if not given, <code>command.name</code> is used</p> <code>None</code>"},{"location":"reference/api/#pdm.core.Project","title":"<code>pdm.core.Project</code>","text":"<p>Core project class.</p> <p>Parameters:</p> Name Type Description Default <code>core</code> <code>Core</code> <p>The core instance.</p> required <code>root_path</code> <code>str | Path | None</code> <p>The root path of the project.</p> required <code>is_global</code> <code>bool</code> <p>Whether the project is global.</p> <code>False</code> <code>global_config</code> <code>str | Path | None</code> <p>The path to the global config file.</p> <code>None</code>"},{"location":"reference/api/#pdm.project.core.Project.config","title":"<code>config: Mapping[str, Any]</code>  <code>cached</code> <code>property</code>","text":"<p>A read-only dict configuration</p>"},{"location":"reference/api/#pdm.project.core.Project.default_source","title":"<code>default_source: RepositoryConfig</code>  <code>property</code>","text":"<p>Get the default source from the pypi setting</p>"},{"location":"reference/api/#pdm.project.core.Project.project_config","title":"<code>project_config: Config</code>  <code>cached</code> <code>property</code>","text":"<p>Read-and-writable configuration dict for project settings</p>"},{"location":"reference/api/#pdm.project.core.Project.find_interpreters","title":"<code>find_interpreters(python_spec=None, search_venv=None)</code>","text":"<p>Return an iterable of interpreter paths that matches the given specifier,</p> which can be <ol> <li>a version specifier like 3.7</li> <li>an absolute path</li> <li>a short name like python3</li> <li>None that returns all possible interpreters</li> </ol>"},{"location":"reference/api/#pdm.project.core.Project.get_provider","title":"<code>get_provider(strategy='all', tracked_names=None, for_install=False, ignore_compatibility=True, direct_minimal_versions=False)</code>","text":"<p>Build a provider class for resolver.</p> <p>:param strategy: the resolve strategy :param tracked_names: the names of packages that needs to update :param for_install: if the provider is for install :param ignore_compatibility: if the provider should ignore the compatibility when evaluating candidates :param direct_minimal_versions: if the provider should prefer minimal versions instead of latest :returns: The provider object</p>"},{"location":"reference/api/#pdm.project.core.Project.get_reporter","title":"<code>get_reporter(requirements, tracked_names=None, spinner=None)</code>","text":"<p>Return the reporter object to construct a resolver.</p> <p>:param requirements: requirements to resolve :param tracked_names: the names of packages that needs to update :param spinner: optional spinner object :returns: a reporter</p>"},{"location":"reference/api/#pdm.project.core.Project.get_repository","title":"<code>get_repository(cls=None, ignore_compatibility=True)</code>","text":"<p>Get the repository object</p>"},{"location":"reference/api/#pdm.project.core.Project.resolve_interpreter","title":"<code>resolve_interpreter()</code>","text":"<p>Get the Python interpreter path.</p>"},{"location":"reference/api/#pdm.project.core.Project.use_pyproject_dependencies","title":"<code>use_pyproject_dependencies(group, dev=False)</code>","text":"<p>Get the dependencies array and setter in the pyproject.toml Return a tuple of two elements, the first is the dependencies array, and the second value is a callable to set the dependencies array back.</p>"},{"location":"reference/api/#pdm.project.core.Project.write_lockfile","title":"<code>write_lockfile(toml_data, show_message=True, write=True, **_kwds)</code>","text":"<p>Write the lock file to disk.</p>"},{"location":"reference/api/#signals","title":"Signals","text":"<p>Added in version 1.12.0</p> <p>The signal definition for PDM.</p> Example <pre><code>from pdm.signals import post_init, post_install\n\ndef on_post_init(project):\n    project.core.ui.echo(\"Project initialized\")\n# Connect to the signal\npost_init.connect(on_post_init)\n# Or use as a decorator\n@post_install.connect\ndef on_post_install(project, candidates, dry_run):\n    project.core.ui.echo(\"Project install succeeded\")\n</code></pre>"},{"location":"reference/api/#pdm.signals.post_build","title":"<code>post_build: NamedSignal = pdm_signals.signal('post_build')</code>  <code>module-attribute</code>","text":"<p>Called after a project is built.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>artifacts</code> <code>Sequence[str]</code> <p>The locations of built artifacts</p> required <code>config_settings</code> <code>dict[str, str] | None</code> <p>Additional config settings passed via args</p> required"},{"location":"reference/api/#pdm.signals.post_init","title":"<code>post_init: NamedSignal = pdm_signals.signal('post_init')</code>  <code>module-attribute</code>","text":"<p>Called after a project is initialized.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required"},{"location":"reference/api/#pdm.signals.post_install","title":"<code>post_install: NamedSignal = pdm_signals.signal('post_install')</code>  <code>module-attribute</code>","text":"<p>Called after a project is installed.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>candidates</code> <code>dict[str, Candidate]</code> <p>The candidates installed</p> required <code>dry_run</code> <code>bool</code> <p>If true, won't perform any actions</p> required"},{"location":"reference/api/#pdm.signals.post_lock","title":"<code>post_lock: NamedSignal = pdm_signals.signal('post_lock')</code>  <code>module-attribute</code>","text":"<p>Called after a project is locked.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>resolution</code> <code>dict[str, Candidate]</code> <p>The resolved candidates</p> required <code>dry_run</code> <code>bool</code> <p>If true, won't perform any actions</p> required"},{"location":"reference/api/#pdm.signals.post_publish","title":"<code>post_publish: NamedSignal = pdm_signals.signal('post_publish')</code>  <code>module-attribute</code>","text":"<p>Called after a project is published.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required"},{"location":"reference/api/#pdm.signals.post_run","title":"<code>post_run: NamedSignal = pdm_signals.signal('post_run')</code>  <code>module-attribute</code>","text":"<p>Called after any run.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>script</code> <code>str</code> <p>the script name</p> required <code>args</code> <code>Sequence[str]</code> <p>the command line provided arguments</p> required"},{"location":"reference/api/#pdm.signals.post_script","title":"<code>post_script: NamedSignal = pdm_signals.signal('post_script')</code>  <code>module-attribute</code>","text":"<p>Called after any script.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>script</code> <code>str</code> <p>the script name</p> required <code>args</code> <code>Sequence[str]</code> <p>the command line provided arguments</p> required"},{"location":"reference/api/#pdm.signals.post_use","title":"<code>post_use: NamedSignal = pdm_signals.signal('post_use')</code>  <code>module-attribute</code>","text":"<p>Called after use switched to a new Python version.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>python</code> <code>PythonInfo</code> <p>Information about the new Python interpreter</p> required"},{"location":"reference/api/#pdm.signals.pre_build","title":"<code>pre_build: NamedSignal = pdm_signals.signal('pre_build')</code>  <code>module-attribute</code>","text":"<p>Called before a project is built.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>dest</code> <code>str</code> <p>The destination location</p> required <code>config_settings</code> <code>dict[str, str] | None</code> <p>Additional config settings passed via args</p> required"},{"location":"reference/api/#pdm.signals.pre_install","title":"<code>pre_install: NamedSignal = pdm_signals.signal('pre_install')</code>  <code>module-attribute</code>","text":"<p>Called before a project is installed.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>candidates</code> <code>dict[str, Candidate]</code> <p>The candidates to install</p> required <code>dry_run</code> <code>bool</code> <p>If true, won't perform any actions</p> required"},{"location":"reference/api/#pdm.signals.pre_invoke","title":"<code>pre_invoke: NamedSignal = pdm_signals.signal('pre_invoke')</code>  <code>module-attribute</code>","text":"<p>Called before any command is invoked.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>command</code> <code>str | None</code> <p>the command name</p> required <code>options</code> <code>Namespace</code> <p>the parsed arguments</p> required"},{"location":"reference/api/#pdm.signals.pre_lock","title":"<code>pre_lock: NamedSignal = pdm_signals.signal('pre_lock')</code>  <code>module-attribute</code>","text":"<p>Called before a project is locked.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>requirements</code> <code>list[Requirement]</code> <p>The requirements to lock</p> required <code>dry_run</code> <code>bool</code> <p>If true, won't perform any actions</p> required"},{"location":"reference/api/#pdm.signals.pre_publish","title":"<code>pre_publish: NamedSignal = pdm_signals.signal('pre_publish')</code>  <code>module-attribute</code>","text":"<p>Called before a project is published.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required"},{"location":"reference/api/#pdm.signals.pre_run","title":"<code>pre_run: NamedSignal = pdm_signals.signal('pre_run')</code>  <code>module-attribute</code>","text":"<p>Called before any run.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>script</code> <code>str</code> <p>the script name</p> required <code>args</code> <code>Sequence[str]</code> <p>the command line provided arguments</p> required"},{"location":"reference/api/#pdm.signals.pre_script","title":"<code>pre_script: NamedSignal = pdm_signals.signal('pre_script')</code>  <code>module-attribute</code>","text":"<p>Called before any script.</p> <p>Parameters:</p> Name Type Description Default <code>project</code> <code>Project</code> <p>The project object</p> required <code>script</code> <code>str</code> <p>the script name</p> required <code>args</code> <code>Sequence[str]</code> <p>the command line provided arguments</p> required"},{"location":"reference/build/","title":"Build Configuration","text":"<p><code>pdm</code> uses the PEP 517 to build the package. It acts as a build frontend that calls the build backend to build the package.</p> <p>A build backend is what drives the build system to build source distributions and wheels from arbitrary source trees.</p> <p>If you run <code>pdm init</code>, PDM will let you choose the build backend to use. Unlike other package managers, PDM does not force you to use a specific build backend. You can choose the one you like. Here is a list of build backends and corresponding configurations initially supported by PDM:</p> pdm-backendsetuptoolsflithatchlingmaturin <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"pdm-backend\"]\nbuild-backend = \"pdm.backend\"\n</code></pre> <p> Read the docs</p> <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"setuptools\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n</code></pre> <p> Read the docs</p> <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"flit_core &gt;=3.2,&lt;4\"]\nbuild-backend = \"flit_core.buildapi\"\n</code></pre> <p> Read the docs</p> <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n</code></pre> <p> Read the docs</p> <p><code>pyproject.toml</code> configuration:</p> <pre><code>[build-system]\nrequires = [\"maturin&gt;=1.4,&lt;2.0\"]\nbuild-backend = \"maturin\"\n</code></pre> <p> Read the docs</p> <p>Apart from the above mentioned backends, you can also use any other backend that supports PEP 621, however, poetry-core is not supported because it does not support reading PEP 621 metadata.</p> <p>Info</p> <p>If you are using a custom build backend that is not in the above list, PDM will handle the relative paths as PDM-style(<code>${PROJECT_ROOT}</code> variable).</p>"},{"location":"reference/cli/","title":"CLI Reference","text":""},{"location":"reference/cli/#pdm","title":"pdm","text":"<p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-V</code>, <code>--version</code>: Show the version and exit</li> <li><code>-c</code>, <code>--config</code>: Specify another config file path [env var: <code>PDM_CONFIG_FILE</code>] </li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--no-cache</code>: Disable the cache for the current command. [env var: <code>PDM_NO_CACHE</code>]</li> <li><code>-I</code>, <code>--ignore-python</code>: Ignore the Python path saved in<code>.pdm-python</code>. [env var: <code>PDM_IGNORE_SAVED_PYTHON</code>]</li> <li><code>--pep582</code> <code>SHELL</code>: Print the command line to be eval'd by the shell</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#add","title":"add","text":"<p>Add package(s) to pyproject.toml and install them</p> <p>Package Arguments:</p> <ul> <li><code>-e</code>, <code>--editable</code>: Specify editable packages</li> <li><code>packages</code>: Specify packages</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--frozen-lockfile</code>, <code>--no-lock</code>: Don't try to create or update the lockfile. [env var: <code>PDM_FROZEN_LOCKFILE</code>]</li> <li><code>--save-compatible</code>: Save compatible version specifiers</li> <li><code>--save-wildcard</code>: Save wildcard version specifiers</li> <li><code>--save-exact</code>: Save exact version specifiers</li> <li><code>--save-minimum</code>: Save minimum version specifiers</li> <li><code>--update-reuse</code>: Reuse pinned versions already present in lock file if possible</li> <li><code>--update-eager</code>: Try to update the packages and their dependencies recursively</li> <li><code>--update-all</code>: Update all dependencies and sub-dependencies</li> <li><code>--update-reuse-installed</code>: Reuse installed packages if possible</li> <li><code>--pre</code>, <code>--prerelease</code>: Allow prereleases to be pinned</li> <li><code>--stable</code>: Only allow stable versions to be pinned (default: <code>True</code>)</li> <li><code>-u</code>, <code>--unconstrained</code>: Ignore the version constraint of packages</li> <li><code>--dry-run</code>: Show the difference only and don't perform any action</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>-d</code>, <code>--dev</code>: Add packages into dev dependencies</li> <li><code>-G</code>, <code>--group</code>: Specify the target dependency group to add into</li> <li><code>--no-sync</code>: Only write<code>pyproject.toml</code> and do not sync the working set (default: <code>False</code>)</li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul>"},{"location":"reference/cli/#build","title":"build","text":"<p>Build artifacts for distribution</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> <li><code>--no-sdist</code>: Don't build source tarballs (default: <code>False</code>)</li> <li><code>--no-wheel</code>: Don't build wheels (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dest</code>: Target directory to put artifacts (default: <code>dist</code>)</li> <li><code>--no-clean</code>: Do not clean the target directory (default: <code>False</code>)</li> </ul>"},{"location":"reference/cli/#cache","title":"cache","text":"<p>Control the caches of PDM</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#clear","title":"clear","text":"<p>Clean all the files under cache directory</p> <p>Positional Arguments:</p> <ul> <li><code>type</code>: Clear the given type of caches</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#remove","title":"remove","text":"<p>Remove files matching the given pattern</p> <p>Positional Arguments:</p> <ul> <li><code>pattern</code>: The pattern to remove</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#list","title":"list","text":"<p>List the built wheels stored in the cache</p> <p>Positional Arguments:</p> <ul> <li><code>pattern</code>: The pattern to list (default: <code>*</code>)</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#info","title":"info","text":"<p>Show the info and current size of caches</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#completion","title":"completion","text":"<p>Generate completion scripts for the given shell</p> <p>Positional Arguments:</p> <ul> <li><code>shell</code>: The shell to generate the scripts for. If not given, PDM will properly guess from <code>SHELL</code> env var.</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> </ul>"},{"location":"reference/cli/#config","title":"config","text":"<p>Display the current configuration</p> <p>Positional Arguments:</p> <ul> <li><code>key</code>: Config key</li> <li><code>value</code>: Config value</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-l</code>, <code>--local</code>: Set config in the project's local configuration file</li> <li><code>-d</code>, <code>--delete</code>: Unset a configuration key</li> <li><code>-e</code>, <code>--edit</code>: Edit the configuration file in the default editor(defined by EDITOR env var)</li> </ul>"},{"location":"reference/cli/#export","title":"export","text":"<p>Export the locked packages set to other formats</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>-f</code>, <code>--format</code>: Specify the export file format (default: <code>requirements</code>)</li> <li><code>--no-hashes</code>, <code>--without-hashes</code>: Don't include artifact hashes (default: <code>False</code>)</li> <li><code>--no-markers</code>: Don't include platform markers (default: <code>False</code>)</li> <li><code>-o</code>, <code>--output</code>: Write output to the given file, or print to stdout if not given</li> <li><code>--pyproject</code>: Read the list of packages from<code>pyproject.toml</code></li> <li><code>--expandvars</code>: Expand environment variables in requirements</li> <li><code>--self</code>: Include the project itself</li> <li><code>--editable-self</code>: Include the project itself as an editable dependency</li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies (default: <code>True</code>)</li> </ul>"},{"location":"reference/cli/#fix","title":"fix","text":"<p>Fix the project problems according to the latest version of PDM</p> <p>Positional Arguments:</p> <ul> <li><code>problem</code>: Fix the specific problem, or all if not given</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--dry-run</code>: Only show the problems</li> </ul>"},{"location":"reference/cli/#import","title":"import","text":"<p>Import project metadata from other formats</p> <p>Positional Arguments:</p> <ul> <li><code>filename</code>: The file name</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-d</code>, <code>--dev</code>: import packages into dev dependencies</li> <li><code>-G</code>, <code>--group</code>: Specify the target dependency group to import into</li> <li><code>-f</code>, <code>--format</code>: Specify the file format explicitly</li> </ul>"},{"location":"reference/cli/#info_1","title":"info","text":"<p>Show the project information</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>--python</code>: Show the interpreter path</li> <li><code>--where</code>: Show the project root path</li> <li><code>--packages</code>: Show the local packages root</li> <li><code>--env</code>: Show PEP 508 environment markers</li> <li><code>--json</code>: Dump the information in JSON</li> </ul>"},{"location":"reference/cli/#init","title":"init","text":"<p>Initialize a pyproject.toml for PDM</p> <p>Positional Arguments:</p> <ul> <li><code>template</code>: Specify the project template, which can be a local path or a Git URL</li> <li><code>generator_args</code>: Arguments passed to the generator</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--copier</code>: Use Copier to generate project [not installed] (default: <code>builtin</code>)</li> <li><code>--cookiecutter</code>: Use Cookiecutter to generate project [not installed] (default: <code>builtin</code>)</li> <li><code>-r</code>, <code>--overwrite</code>: Overwrite existing files</li> </ul> <p>Builtin Generator Options:</p> <ul> <li><code>-n</code>, <code>--non-interactive</code>: Don't ask questions but use default values</li> <li><code>--python</code>: Specify the Python version/path to use</li> <li><code>--dist</code>, <code>--lib</code>: Create a package for distribution</li> <li><code>--backend</code>: Specify the build backend, which implies --dist</li> </ul>"},{"location":"reference/cli/#install","title":"install","text":"<p>Install dependencies from lock file</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--dry-run</code>: Show the difference only and don't perform any action</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--frozen-lockfile</code>, <code>--no-lock</code>: Don't try to create or update the lockfile. [env var: <code>PDM_FROZEN_LOCKFILE</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>--check</code>: Check if the lock file is up to date and fail otherwise</li> <li><code>--plugins</code>: Install the plugins specified in<code>pyproject.toml</code></li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies (default: <code>True</code>)</li> </ul>"},{"location":"reference/cli/#list_1","title":"list","text":"<p>List packages installed in the current working set</p> <p>Positional Arguments:</p> <ul> <li><code>patterns</code>: Filter packages by patterns. e.g. pdm list requests- flask-. In --tree mode, only show the subtree of the matched packages.</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>--freeze</code>: Show the installed dependencies in pip's requirements.txt format</li> <li><code>--tree</code>, <code>--graph</code>: Display a tree of dependencies</li> <li><code>-r</code>, <code>--reverse</code>: Reverse the dependency tree</li> <li><code>--resolve</code>: Resolve all requirements to output licenses (instead of just showing those currently installed)</li> <li><code>--fields</code>: Select information to output as a comma separated string. All fields: groups,homepage,licenses,location,name,version. (default: <code>name,version,location</code>)</li> <li><code>--sort</code>: Sort the output using a given field name. If nothing is set, no sort is applied. Multiple fields can be combined with ','.</li> <li><code>--csv</code>: Output dependencies in CSV document format</li> <li><code>--json</code>: Output dependencies in JSON document format</li> <li><code>--markdown</code>: Output dependencies and legal notices in markdown document format - best effort basis</li> <li><code>--include</code>: Dependency groups to include in the output. By default all are included</li> <li><code>--exclude</code>: Exclude dependency groups from the output</li> </ul>"},{"location":"reference/cli/#lock","title":"lock","text":"<p>Resolve and lock dependencies</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--refresh</code>: Don't update pinned versions, only refresh the lock file</li> <li><code>--check</code>: Check if the lock file is up to date and quit</li> <li><code>--update-reuse</code>: Reuse pinned versions already present in lock file if possible (default: <code>all</code>)</li> <li><code>--update-reuse-installed</code>: Reuse installed packages if possible</li> <li><code>--exclude-newer</code>: Exclude packages newer than the given UTC date in format <code>YYYY-MM-DD[THH:MM:SSZ]</code></li> </ul> <p>Lock Strategy:</p> <ul> <li><code>--strategy</code>, <code>-S</code> <code>STRATEGY</code>: Specify lock strategy (cross_platform, static_urls, direct_minimal_versions, inherit_metadata). Add 'no_' prefix to disable. Can be supplied multiple times or split by comma.</li> <li><code>--no-cross-platform</code>: [DEPRECATED] Only lock packages for the current platform</li> <li><code>--static-urls</code>: [DEPRECATED] Store static file URLs in the lockfile</li> <li><code>--no-static-urls</code>: [DEPRECATED] Do not store static file URLs in the lockfile</li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies (default: <code>True</code>)</li> </ul>"},{"location":"reference/cli/#publish","title":"publish","text":"<p>Build and publish the project to PyPI</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>-r</code>, <code>--repository</code>: The repository name or url to publish the package to [env var: <code>PDM_PUBLISH_REPO</code>]</li> <li><code>-u</code>, <code>--username</code>: The username to access the repository [env var: <code>PDM_PUBLISH_USERNAME</code>]</li> <li><code>-P</code>, <code>--password</code>: The password to access the repository [env var: <code>PDM_PUBLISH_PASSWORD</code>]</li> <li><code>-S</code>, <code>--sign</code>: Upload the package with PGP signature</li> <li><code>-i</code>, <code>--identity</code>: GPG identity used to sign files.</li> <li><code>-c</code>, <code>--comment</code>: The comment to include with the distribution file.</li> <li><code>--no-build</code>: Don't build the package before publishing (default: <code>False</code>)</li> <li><code>--skip-existing</code>: Skip uploading files that already exist. This may not work with some repository implementations.</li> <li><code>--no-very-ssl</code>: Disable SSL verification</li> <li><code>--ca-certs</code>: The path to a PEM-encoded Certificate Authority bundle to use for publish server validation [env var: <code>PDM_PUBLISH_CA_CERTS</code>]</li> </ul>"},{"location":"reference/cli/#remove_1","title":"remove","text":"<p>Remove packages from pyproject.toml</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify the packages to remove</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--dry-run</code>: Show the difference only and don't perform any action</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--frozen-lockfile</code>, <code>--no-lock</code>: Don't try to create or update the lockfile. [env var: <code>PDM_FROZEN_LOCKFILE</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-d</code>, <code>--dev</code>: Remove packages from dev dependencies</li> <li><code>-G</code>, <code>--group</code>: Specify the target dependency group to remove from</li> <li><code>--no-sync</code>: Only write<code>pyproject.toml</code> and do not uninstall packages (default: <code>False</code>)</li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul>"},{"location":"reference/cli/#run","title":"run","text":"<p>Run commands or scripts with local packages loaded</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-l</code>, <code>--list</code>: Show all available scripts defined in<code>pyproject.toml</code></li> <li><code>-j</code>, <code>--json</code>: Output all scripts infos in JSON</li> </ul> <p>Execution Parameters:</p> <ul> <li><code>-s</code>, <code>--site-packages</code>: Load site-packages from the selected interpreter</li> <li><code>script</code>: The command to run</li> <li><code>args</code>: Arguments that will be passed to the command</li> </ul>"},{"location":"reference/cli/#search","title":"search","text":"<p>Search for PyPI packages</p> <p>Positional Arguments:</p> <ul> <li><code>query</code>: Query string to search</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#self","title":"self","text":"<p>Manage the PDM program itself (previously known as plugin)</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#list_2","title":"list","text":"<p>List all packages installed with PDM</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--plugins</code>: List plugins only</li> </ul>"},{"location":"reference/cli/#add_1","title":"add","text":"<p>Install packages to the PDM's environment</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify one or many package names, each package can have a version specifier</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--pip-args</code>: Arguments that will be passed to pip install</li> </ul>"},{"location":"reference/cli/#remove_2","title":"remove","text":"<p>Remove packages from PDM's environment</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify one or many package names</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--pip-args</code>: Arguments that will be passed to pip uninstall</li> <li><code>-y</code>, <code>--yes</code>: Answer yes on the question</li> </ul>"},{"location":"reference/cli/#update","title":"update","text":"<p>Update PDM itself</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--head</code>: Update to the latest commit on the main branch</li> <li><code>--pre</code>: Update to the latest prerelease version</li> <li><code>--pip-args</code>: Additional arguments that will be passed to pip install</li> </ul>"},{"location":"reference/cli/#plugin","title":"plugin","text":"<p>Manage the PDM program itself (previously known as plugin)</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#list_3","title":"list","text":"<p>List all packages installed with PDM</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--plugins</code>: List plugins only</li> </ul>"},{"location":"reference/cli/#add_2","title":"add","text":"<p>Install packages to the PDM's environment</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify one or many package names, each package can have a version specifier</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--pip-args</code>: Arguments that will be passed to pip install</li> </ul>"},{"location":"reference/cli/#remove_3","title":"remove","text":"<p>Remove packages from PDM's environment</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: Specify one or many package names</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--pip-args</code>: Arguments that will be passed to pip uninstall</li> <li><code>-y</code>, <code>--yes</code>: Answer yes on the question</li> </ul>"},{"location":"reference/cli/#update_1","title":"update","text":"<p>Update PDM itself</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>--head</code>: Update to the latest commit on the main branch</li> <li><code>--pre</code>: Update to the latest prerelease version</li> <li><code>--pip-args</code>: Additional arguments that will be passed to pip install</li> </ul>"},{"location":"reference/cli/#show","title":"show","text":"<p>Show the package information</p> <p>Positional Arguments:</p> <ul> <li><code>package</code>: Specify the package name, or show this package if not given</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>--name</code>: Show name</li> <li><code>--version</code>: Show version</li> <li><code>--summary</code>: Show summary</li> <li><code>--license</code>: Show license</li> <li><code>--platform</code>: Show platform</li> <li><code>--keywords</code>: Show keywords</li> </ul>"},{"location":"reference/cli/#sync","title":"sync","text":"<p>Synchronize the current working set with lock file</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--dry-run</code>: Show the difference only and don't perform any action</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--clean</code>: Clean packages not in the lockfile</li> <li><code>--only-keep</code>: Only keep the selected packages</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-r</code>, <code>--reinstall</code>: Force reinstall existing dependencies</li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies (default: <code>True</code>)</li> </ul>"},{"location":"reference/cli/#update_2","title":"update","text":"<p>Update package(s) in pyproject.toml</p> <p>Positional Arguments:</p> <ul> <li><code>packages</code>: If packages are given, only update them</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-L</code>, <code>--lockfile</code>: Specify another lockfile path. Default:<code>pdm.lock</code>. [env var: <code>PDM_LOCKFILE</code>]</li> <li><code>--frozen-lockfile</code>, <code>--no-lock</code>: Don't try to create or update the lockfile. [env var: <code>PDM_FROZEN_LOCKFILE</code>]</li> <li><code>--save-compatible</code>: Save compatible version specifiers</li> <li><code>--save-wildcard</code>: Save wildcard version specifiers</li> <li><code>--save-exact</code>: Save exact version specifiers</li> <li><code>--save-minimum</code>: Save minimum version specifiers</li> <li><code>--update-reuse</code>: Reuse pinned versions already present in lock file if possible</li> <li><code>--update-eager</code>: Try to update the packages and their dependencies recursively</li> <li><code>--update-all</code>: Update all dependencies and sub-dependencies</li> <li><code>--update-reuse-installed</code>: Reuse installed packages if possible</li> <li><code>--pre</code>, <code>--prerelease</code>: Allow prereleases to be pinned</li> <li><code>--stable</code>: Only allow stable versions to be pinned (default: <code>True</code>)</li> <li><code>-u</code>, <code>--unconstrained</code>: Ignore the version constraint of packages</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>--venv</code> <code>NAME</code>: Run the command in the virtual environment with the given key. [env var: <code>PDM_IN_VENV</code>]</li> <li><code>-t</code>, <code>--top</code>: Only update those listed in<code>pyproject.toml</code></li> <li><code>--dry-run</code>, <code>--outdated</code>: Show the difference only without modifying the lockfile content</li> <li><code>--no-sync</code>: Only update lock file but do not sync packages (default: <code>False</code>)</li> </ul> <p>Install Options:</p> <ul> <li><code>--no-editable</code>: Install non-editable versions for all packages. [env var: <code>PDM_NO_EDITABLE</code>]</li> <li><code>--no-self</code>: Don't install the project itself. [env var: <code>PDM_NO_SELF</code>]</li> <li><code>--fail-fast</code>, <code>-x</code>: Abort on first installation error</li> <li><code>--no-isolation</code>: Disable isolation when building a source distribution that follows PEP 517, as in: build dependencies specified by PEP 518 must be already installed if this option is used.</li> <li><code>--config-setting</code>, <code>-C</code>: Pass options to the builder. options with a value must be specified after \"=\": <code>--config-setting=key(=value)</code> or <code>-Ckey(=value)</code></li> </ul> <p>Dependencies Selection:</p> <ul> <li><code>-G</code>, <code>--group</code>, <code>--with</code> <code>GROUP</code>: Select group of optional-dependencies separated by comma or dev-dependencies (with <code>-d</code>). Can be supplied multiple times, use<code>:all</code> to include all groups under the same species.</li> <li><code>--without</code>: Exclude groups of optional-dependencies or dev-dependencies</li> <li><code>--no-default</code>: Don't include dependencies from the default group (default: <code>False</code>)</li> <li><code>-d</code>, <code>--dev</code>: Select dev dependencies</li> <li><code>--prod</code>, <code>--production</code>: Unselect dev dependencies</li> </ul>"},{"location":"reference/cli/#use","title":"use","text":"<p>Use the given python version or path as base interpreter</p> <p>Positional Arguments:</p> <ul> <li><code>python</code>: Specify the Python version or path</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-g</code>, <code>--global</code>: Use the global project, supply the project root with <code>-p</code> option</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>-k</code>, <code>--skip</code>: Skip some tasks and/or hooks by their comma-separated names. Can be supplied multiple times. Use<code>:all</code> to skip all hooks. Use<code>:pre</code> and<code>:post</code> to skip all pre or post hooks.</li> <li><code>-f</code>, <code>--first</code>: Select the first matched interpreter</li> <li><code>-i</code>, <code>--ignore-remembered</code>: Ignore the remembered selection</li> <li><code>--venv</code>: Use the interpreter in the virtual environment with the given name</li> </ul>"},{"location":"reference/cli/#venv","title":"venv","text":"<p>Virtualenv management</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-p</code>, <code>--project</code>: Specify another path as the project root, which changes the base of<code>pyproject.toml</code> and <code>__pypackages__</code> [env var: <code>PDM_PROJECT</code>]</li> <li><code>--path</code>: Show the path to the given virtualenv</li> <li><code>--python</code>: Show the python interpreter path for the given virtualenv</li> </ul> <p>Commands:</p>"},{"location":"reference/cli/#create","title":"create","text":"<p>Create a virtualenv</p> <p>Positional Arguments:</p> <ul> <li><code>python</code>: Specify which python should be used to create the virtualenv</li> <li><code>venv_args</code>: Additional arguments that will be passed to the backend</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-w</code>, <code>--with</code>: Specify the backend to create the virtualenv</li> <li><code>-f</code>, <code>--force</code>: Recreate if the virtualenv already exists</li> <li><code>-n</code>, <code>--name</code>: Specify the name of the virtualenv</li> <li><code>--with-pip</code>: Install pip with the virtualenv</li> </ul>"},{"location":"reference/cli/#list_4","title":"list","text":"<p>List all virtualenvs associated with this project</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#remove_4","title":"remove","text":"<p>Remove the virtualenv with the given name</p> <p>Positional Arguments:</p> <ul> <li><code>env</code>: The key of the virtualenv</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-y</code>, <code>--yes</code>: Answer yes on the following question</li> </ul>"},{"location":"reference/cli/#activate","title":"activate","text":"<p>Print the command to activate the virtualenv with the given name</p> <p>Positional Arguments:</p> <ul> <li><code>env</code>: The key of the virtualenv</li> </ul> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> </ul>"},{"location":"reference/cli/#purge","title":"purge","text":"<p>Purge selected/all created Virtualenvs</p> <p>Options:</p> <ul> <li><code>-h</code>, <code>--help</code>: Show this help message and exit.</li> <li><code>-v</code>, <code>--verbose</code>: Use <code>-v</code> for detailed output and <code>-vv</code> for more detailed</li> <li><code>-q</code>, <code>--quiet</code>: Suppress output</li> <li><code>-f</code>, <code>--force</code>: Force purging without prompting for confirmation</li> <li><code>-i</code>, <code>--interactive</code>: Interactively purge selected Virtualenvs</li> </ul>"},{"location":"reference/configuration/","title":"Configurations","text":""},{"location":"reference/configuration/#color-theme","title":"Color Theme","text":"<p>The default theme used by PDM is as follows:</p> Key Default Style <code>primary</code> cyan <code>success</code> green <code>warning</code> yellow <code>error</code> red <code>info</code> blue <code>req</code> bold green <p>You can change the theme colors with <code>pdm config</code> command. For example, to change the <code>primary</code> color to <code>magenta</code>:</p> <pre><code>pdm config theme.primary magenta\n</code></pre> <p>Or use a hex color code:</p> <pre><code>pdm config theme.success '#51c7bd'\n</code></pre>"},{"location":"reference/configuration/#available-configurations","title":"Available Configurations","text":"<p>The following configuration items can be retrieved and modified by <code>pdm config</code> command.</p> <p>Environment Variable Overrides</p> <p>If the corresponding env var is set, the value will take precedence over what is saved in the config file.</p> Config Item Description Default Value Available in Project Env var <code>cache_dir</code> The root directory of cached files <code>/home/runner/.cache/pdm</code> No <code>PDM_CACHE_DIR</code> <code>log_dir</code> The root directory of log files <code>/home/runner/.local/state/pdm/log</code> No <code>PDM_LOG_DIR</code> <code>check_update</code> Check if there is any newer version available <code>True</code> No <code>PDM_CHECK_UPDATE</code> <code>build_isolation</code> Isolate build environment from the project environment <code>True</code> Yes <code>PDM_BUILD_ISOLATION</code> <code>request_timeout</code> The timeout for network requests in seconds <code>15</code> No <code>PDM_REQUEST_TIMEOUT</code> <code>global_project.fallback</code> Use the global project implicitly if no local project is found <code>False</code> No <code>global_project.fallback_verbose</code> If True show message when global project is used implicitly <code>True</code> No <code>global_project.path</code> The path to the global project <code>/home/runner/.config/pdm/global-project</code> No <code>global_project.user_site</code> Whether to install to user site <code>False</code> No <code>strategy.update</code> The default strategy for updating packages <code>reuse</code> Yes <code>strategy.save</code> Specify how to save versions when a package is added <code>minimum</code> Yes <code>strategy.resolve_max_rounds</code> Specify the max rounds of resolution process <code>10000</code> Yes <code>PDM_RESOLVE_MAX_ROUNDS</code> <code>strategy.inherit_metadata</code> Inherit the groups and markers from parents for each package <code>True</code> Yes <code>install.parallel</code> Whether to perform installation and uninstallation in parallel <code>True</code> Yes <code>PDM_INSTALL_PARALLEL</code> <code>install.cache</code> Cache wheel installation and only put symlinks in the library root <code>False</code> Yes <code>install.cache_method</code> Specify how to create links to the caches(<code>symlink/hardlink</code>) <code>symlink</code> Yes <code>python.providers</code> List of python provider names for findpython <code>[]</code> Yes <code>python.use_pyenv</code> Use the pyenv interpreter <code>True</code> Yes <code>python.use_venv</code> Use virtual environments when available <code>True</code> Yes <code>PDM_USE_VENV</code> <code>pypi.url</code> The URL of PyPI mirror, defaults to https://pypi.org/simple <code>https://pypi.org/simple</code> Yes <code>PDM_PYPI_URL</code> <code>pypi.verify_ssl</code> Verify SSL certificate when query PyPI <code>True</code> Yes <code>pypi.username</code> The username to access PyPI Yes <code>PDM_PYPI_USERNAME</code> <code>pypi.password</code> The password to access PyPI Yes <code>PDM_PYPI_PASSWORD</code> <code>pypi.ca_certs</code> Path to a CA certificate bundle used for verifying the identity of the PyPI server No <code>pypi.ignore_stored_index</code> Ignore the configured indexes <code>False</code> Yes <code>PDM_IGNORE_STORED_INDEX</code> <code>pypi.client_cert</code> Path to client certificate file, or combined cert/key file No <code>pypi.client_key</code> Path to client cert keyfile, if not in pypi.client_cert No <code>pypi.json_api</code> Consult PyPI's JSON API for package metadata <code>False</code> Yes <code>PDM_PYPI_JSON_API</code> <code>venv.location</code> Parent directory for virtualenvs <code>/home/runner/.local/share/pdm/venvs</code> No <code>venv.backend</code> Default backend to create virtualenv <code>virtualenv</code> Yes <code>PDM_VENV_BACKEND</code> <code>venv.in_project</code> Create virtualenv in <code>.venv</code> under project root <code>True</code> Yes <code>PDM_VENV_IN_PROJECT</code> <code>venv.prompt</code> Define a custom template to be displayed in the prompt when virtualenv isactive. Variables <code>project_name</code> and <code>python_version</code> are available forformatting <code>{project_name}-{python_version}</code> Yes <code>PDM_VENV_PROMPT</code> <code>venv.with_pip</code> Install pip when creating a new venv <code>False</code> Yes <code>PDM_VENV_WITH_PIP</code> <code>theme.primary</code> Theme color for primary <code>cyan</code> No <code>theme.success</code> Theme color for success <code>green</code> No <code>theme.warning</code> Theme color for warning <code>yellow</code> No <code>theme.error</code> Theme color for error <code>red</code> No <code>theme.info</code> Theme color for info <code>blue</code> No <code>theme.req</code> Theme color for req <code>bold green</code> No <code>pypi.&lt;name&gt;.url</code> The URL of custom package source <code>https://pypi.org/simple</code> Yes <code>pypi.&lt;name&gt;.username</code> The username to access custom source Yes <code>pypi.&lt;name&gt;.password</code> The password to access custom source Yes <code>pypi.&lt;name&gt;.type</code> <code>index</code> or <code>find_links</code> <code>index</code> Yes <code>pypi.&lt;name&gt;.verify_ssl</code> Verify SSL certificate when query custom source <code>True</code> Yes <code>repository.&lt;name&gt;.url</code> The URL of custom package source <code>https://pypi.org/simple</code> Yes <code>repository.&lt;name&gt;.username</code> The username to access custom repository Yes <code>repository.&lt;name&gt;.password</code> The password to access custom repository Yes <code>repository.&lt;name&gt;.ca_certs</code> Path to a PEM-encoded CA cert bundle (used for server cert verification) The CA certificates from certifi Yes <code>repository.&lt;name&gt;.verify_ssl</code> Verify SSL certificate when uploading to repository <code>True</code> Yes"},{"location":"reference/pep621/","title":"PEP 621 Metadata","text":"<p>The project metadata are stored in the <code>pyproject.toml</code>. The specifications are defined by PEP 621, PEP 631 and PEP 639. Read the detailed specifications in the PEPs.</p> <p>In the following part of this document, metadata should be written under <code>[project]</code> table if not given explicitly.</p>"},{"location":"reference/pep621/#multiline-description","title":"Multiline description","text":"<p>You can split a long description onto multiple lines, thanks to TOML support for multiline strings. Just remember to escape new lines, so the final description appears on one line only in your package metadata. Indentation will be removed as well when escaping new lines:</p> <pre><code>description = \"\"\"\\\n    Lorem ipsum dolor sit amet, consectetur adipiscing elit, \\\n    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. \\\n    Ut enim ad minim veniam, quis nostrud exercitation ullamco \\\n    laboris nisi ut aliquip ex ea commodo consequat.\\\n\"\"\"\n</code></pre> <p>See TOML's specification on strings.</p>"},{"location":"reference/pep621/#package-version","title":"Package version","text":"StaticDynamic <pre><code>[project]\nversion = \"1.0.0\"\n</code></pre> <pre><code>[project]\n...\ndynamic = [\"version\"]\n\n[tool.pdm]\nversion = { source = \"file\", path = \"mypackage/__version__.py\" }\n</code></pre> <p>The version will be read from the <code>mypackage/__version__.py</code> file searching for the pattern: <code>__version__ = \"{version}\"</code>.</p> <p>Read more information about other configurations in dynamic project version from the <code>pdm-backend</code> documentation.</p>"},{"location":"reference/pep621/#python-version","title":"Python version","text":"<p>The required version of Python is specified as the string <code>requires-python</code>:</p> <pre><code>requires-python = \"&gt;=3.9\"\nclassifiers = [\n    \"Programming Language :: Python :: 3\",\n    \"Programming Language :: Python :: 3.9\",\n    \"Programming Language :: Python :: 3.10\",\n    \"Programming Language :: Python :: 3.11\",\n    ...\n]\n</code></pre> <p>Note: As per PEP 621, PDM is not permitted to dynamically update the <code>classifiers</code> section like some other non-compliant tools. Thus, you should also include the appropriate trove classifiers as shown above if you plan on publishing your package on PyPI.</p>"},{"location":"reference/pep621/#license","title":"License","text":"<p>The license is specified as the string <code>license</code>:</p> <pre><code>license = {text = \"BSD-2-Clause\"}\nclassifiers = [\n    \"License :: OSI Approved :: BSD License\",\n    ...\n]\n</code></pre> <p>Note: As per PEP 621, PDM is not permitted to dynamically update the <code>classifiers</code> section like some other non-compliant tools. Thus, you should also include the appropriate trove classifiers as shown above if you plan on publishing your package on PyPI.</p>"},{"location":"reference/pep621/#dependency-specification","title":"Dependency specification","text":"<p>The <code>project.dependencies</code> is an array of dependency specification strings following the PEP 440 and PEP 508.</p> <p>Examples:</p> <pre><code>[project]\n...\ndependencies = [\n# Named requirement\n\"requests\",\n# Named requirement with version specifier\n\"flask &gt;= 1.1.0\",\n# Requirement with environment marker\n\"pywin32; sys_platform == 'win32'\",\n# URL requirement\n\"pip @ git+https://github.com/pypa/pip.git@20.3.1\"\n]\n</code></pre>"},{"location":"reference/pep621/#optional-dependencies","title":"Optional dependencies","text":"<p>You can have some requirements optional, which is similar to <code>setuptools</code>' <code>extras_require</code> parameter.</p> <pre><code>[project.optional-dependencies]\nsocks = [ 'PySocks &gt;= 1.5.6, != 1.5.7, &lt; 2' ]\ntests = [\n'ddt &gt;= 1.2.2, &lt; 2',\n'pytest &lt; 6',\n'mock &gt;= 1.0.1, &lt; 4; python_version &lt; \"3.4\"',\n]\n</code></pre> <p>To install a group of optional dependencies:</p> <pre><code>pdm install -G socks\n</code></pre> <p><code>-G</code> option can be given multiple times to include more than one group.</p>"},{"location":"reference/pep621/#context-variables-expansion","title":"Context variables expansion","text":"<p>Depending on which build backend you are using, PDM will expand some variables in the dependency strings.</p>"},{"location":"reference/pep621/#environment-variables","title":"Environment variables","text":"pdm-backendhatchling <pre><code>[project]\ndependencies = [\"flask @ https://${USERNAME}:${PASSWORD}/artifacts.io/Flask-1.1.2.tar.gz\"]\n</code></pre> <pre><code>[project]\ndependencies = [\"flask @ https://{env:USERNAME}:{env:PASSWORD}/artifacts.io/Flask-1.1.2.tar.gz\"]\n</code></pre> <p>Find more usages here</p> <p>Don't worry about credential leakage, the environment variables will be expanded when needed and kept untouched in the lock file.</p>"},{"location":"reference/pep621/#relative-paths","title":"Relative paths","text":"<p>When you add a package from a relative path, PDM will automatically save it as a relative path for <code>pdm-backend</code> and <code>hatchling</code>.</p> <p>For example, if you run <code>pdm add ./my-package</code>, it will result in the following line in <code>pyproject.toml</code>.</p> pdm-backendhatchling <pre><code>[project]\ndependencies = [\"my-package @ file:///${PROJECT_ROOT}/my-package\"]\n</code></pre> <pre><code>[project]\ndependencies = [\"my-package @ {root:uri}/my-package\"]\n</code></pre> <p>By default, hatchling doesn't support direct references in the dependency string, you need to turn it on in <code>pyproject.toml</code>:</p> <pre><code>[tool.hatch.metadata]\nallow-direct-references = true\n</code></pre> <p>The relative path will be expanded based on the project root when installing or locking.</p>"},{"location":"reference/pep621/#console-scripts","title":"Console scripts","text":"<p>The following content:</p> <pre><code>[project.scripts]\nmycli = \"mycli.__main__:main\"\n</code></pre> <p>will be translated to <code>setuptools</code> style:</p> <pre><code>entry_points = {\n    'console_scripts': [\n        'mycli=mycli.__main__:main'\n    ]\n}\n</code></pre> <p>Also, <code>[project.gui-scripts]</code> will be translated to <code>gui_scripts</code> entry points group in <code>setuptools</code> style.</p>"},{"location":"reference/pep621/#entry-points","title":"Entry points","text":"<p>Other types of entry points are given by <code>[project.entry-points.&lt;type&gt;]</code> section, with the same format of <code>[project.scripts]</code>:</p> <pre><code>[project.entry-points.pytest11]\nmyplugin = \"mypackage.plugin:pytest_plugin\"\n</code></pre> <p>If the entry point name contains dots or other special characters, wrap it in quotes:</p> <pre><code>[project.entry-points.\"flake8.extension\"]\nmyplugin = \"mypackage.plugin:flake8_plugin\"\n</code></pre>"},{"location":"usage/advanced/","title":"Advanced Usage","text":""},{"location":"usage/advanced/#automatic-testing","title":"Automatic Testing","text":""},{"location":"usage/advanced/#use-tox-as-the-runner","title":"Use Tox as the runner","text":"<p>Tox is a great tool for testing against multiple Python versions or dependency sets. You can configure a <code>tox.ini</code> like the following to integrate your testing with PDM:</p> <pre><code>[tox]\nenv_list = py{36,37,38},lint\n\n[testenv]\nsetenv =\nPDM_IGNORE_SAVED_PYTHON=\"1\"\ndeps = pdm\ncommands =\npdm install --dev\npytest tests\n\n[testenv:lint]\ndeps = pdm\ncommands =\npdm install -G lint\nflake8 src/\n</code></pre> <p>To use the virtualenv created by Tox, you should make sure you have set <code>pdm config python.use_venv true</code>. PDM then will install dependencies from <code>pdm lock</code> into the virtualenv. In the dedicated venv you can directly run tools by <code>pytest tests/</code> instead of <code>pdm run pytest tests/</code>.</p> <p>You should also make sure you don't run <code>pdm add/pdm remove/pdm update/pdm lock</code> in the test commands, otherwise the <code>pdm lock</code> file will be modified unexpectedly. Additional dependencies can be supplied with the <code>deps</code> config. Besides, <code>isolated_build</code> and <code>passenv</code> config should be set as the above example to make PDM work properly.</p> <p>To get rid of these constraints, there is a Tox plugin tox-pdm which can ease the usage. You can install it by</p> <pre><code>pip install tox-pdm\n</code></pre> <p>Or,</p> <pre><code>pdm add --dev tox-pdm\n</code></pre> <p>And you can make the <code>tox.ini</code> much tidier as following, :</p> <pre><code>[tox]\nenv_list = py{36,37,38},lint\n\n[testenv]\ngroups = dev\ncommands =\npytest tests\n\n[testenv:lint]\ngroups = lint\ncommands =\nflake8 src/\n</code></pre> <p>See the project's README for a detailed guidance.</p>"},{"location":"usage/advanced/#use-nox-as-the-runner","title":"Use Nox as the runner","text":"<p>Nox is another great tool for automated testing. Unlike tox, Nox uses a standard Python file for configuration.</p> <p>It is much easier to use PDM in Nox, here is an example of <code>noxfile.py</code>:</p> <pre><code>import os\nimport nox\n\nos.environ.update({\"PDM_IGNORE_SAVED_PYTHON\": \"1\"})\n@nox.session\ndef tests(session):\n    session.run_always('pdm', 'install', '-G', 'test', external=True)\n    session.run('pytest')\n\n@nox.session\ndef lint(session):\n    session.run_always('pdm', 'install', '-G', 'lint', external=True)\n    session.run('flake8', '--import-order-style', 'google')\n</code></pre> <p>Note that <code>PDM_IGNORE_SAVED_PYTHON</code> should be set so that PDM can pick up the Python in the virtualenv correctly. Also make sure <code>pdm</code> is available in the <code>PATH</code>. Before running nox, you should also ensure configuration item <code>python.use_venv</code> is true to enable venv reusing.</p>"},{"location":"usage/advanced/#about-pep-582-__pypackages__-directory","title":"About PEP 582 <code>__pypackages__</code> directory","text":"<p>By default, if you run tools by <code>pdm run</code>, <code>__pypackages__</code> will be seen by the program and all subprocesses created by it. This means virtual environments created by those tools are also aware of the packages inside <code>__pypackages__</code>, which result in unexpected behavior in some cases. For <code>nox</code>, you can avoid this by adding a line in <code>noxfile.py</code>:</p> <pre><code>os.environ.pop(\"PYTHONPATH\", None)\n</code></pre> <p>For <code>tox</code>, <code>PYTHONPATH</code> will not be passed to the test sessions so this isn't going to be a problem. Moreover, it is recommended to make <code>nox</code> and <code>tox</code> live in their own pipx environments so you don't need to install for every project. In this case, PEP 582 packages will not be a problem either.</p>"},{"location":"usage/advanced/#use-pdm-in-continuous-integration","title":"Use PDM in Continuous Integration","text":"<p>Only one thing to keep in mind -- PDM can't be installed on Python &lt; 3.7, so if your project is to be tested on those Python versions, you have to make sure PDM is installed on the correct Python version, which can be different from the target Python version the particular job/task is run on.</p> <p>Fortunately, if you are using GitHub Action, there is pdm-project/setup-pdm to make this process easier. Here is an example workflow of GitHub Actions, while you can adapt it for other CI platforms.</p> <pre><code>Testing:\nruns-on: ${{ matrix.os }}\nstrategy:\nmatrix:\npython-version: [3.7, 3.8, 3.9, '3.10', '3.11']\nos: [ubuntu-latest, macOS-latest, windows-latest]\n\nsteps:\n- uses: actions/checkout@v3\n- name: Set up PDM\nuses: pdm-project/setup-pdm@v3\nwith:\npython-version: ${{ matrix.python-version }}\n\n- name: Install dependencies\nrun: |\npdm sync -d -G testing\n- name: Run Tests\nrun: |\npdm run -v pytest tests\n</code></pre> <p>TIPS</p> <p>For GitHub Action users, there is a known compatibility issue on Ubuntu virtual environment. If PDM parallel install is failed on that machine you should either set <code>parallel_install</code> to <code>false</code> or set env <code>LD_PRELOAD=/lib/x86_64-linux-gnu/libgcc_s.so.1</code>. It is already handled by the <code>pdm-project/setup-pdm</code> action.</p> <p>Note</p> <p>If your CI scripts run without a proper user set, you might get permission errors when PDM tries to create its cache directory. To work around this, you can set the HOME environment variable yourself, to a writable directory, for example:</p> <pre><code>export HOME=/tmp/home\n</code></pre>"},{"location":"usage/advanced/#use-pdm-in-a-multi-stage-dockerfile","title":"Use PDM in a multi-stage Dockerfile","text":"<p>It is possible to use PDM in a multi-stage Dockerfile to first install the project and dependencies into <code>__pypackages__</code> and then copy this folder into the final stage, adding it to <code>PYTHONPATH</code>.</p> <pre><code># build stage\nFROM python:3.8 AS builder\n\n# install PDM\nRUN pip install -U pip setuptools wheel\nRUN pip install pdm\n\n# copy files\nCOPY pyproject.toml pdm.lock README.md /project/\nCOPY src/ /project/src\n\n# install dependencies and project into the local packages directory\nWORKDIR /project\nRUN mkdir __pypackages__ &amp;&amp; pdm sync --prod --no-editable\n\n\n# run stage\nFROM python:3.8\n\n# retrieve packages from build stage\nENV PYTHONPATH=/project/pkgs\nCOPY --from=builder /project/__pypackages__/3.8/lib /project/pkgs\n\n# retrieve executables\nCOPY --from=builder /project/__pypackages__/3.8/bin/* /bin/\n\n# set command/entrypoint, adapt to fit your needs\nCMD [\"python\", \"-m\", \"project\"]\n</code></pre>"},{"location":"usage/advanced/#use-pdm-to-manage-a-monorepo","title":"Use PDM to manage a monorepo","text":"<p>With PDM, you can have multiple sub-packages within a single project, each with its own <code>pyproject.toml</code> file. And you can create only one <code>pdm.lock</code> file to lock all dependencies. The sub-packages can have each other as their dependencies. To achieve this, follow these steps:</p> <p><code>project/pyproject.toml</code>:</p> <pre><code>[tool.pdm.dev-dependencies]\ndev = [\n\"-e file:///${PROJECT_ROOT}/packages/foo-core\",\n\"-e file:///${PROJECT_ROOT}/packages/foo-cli\",\n\"-e file:///${PROJECT_ROOT}/packages/foo-app\",\n]\n</code></pre> <p><code>packages/foo-cli/pyproject.toml</code>:</p> <pre><code>[project]\ndependencies = [\"foo-core\"]\n</code></pre> <p><code>packages/foo-app/pyproject.toml</code>:</p> <pre><code>[project]\ndependencies = [\"foo-core\"]\n</code></pre> <p>Now, run <code>pdm install</code> in the project root, and you will get a <code>pdm.lock</code> with all dependencies locked. All sub-packages will be installed in editable mode.</p> <p>Look at the \ud83d\ude80 Example repository for more details.</p>"},{"location":"usage/advanced/#hooks-for-pre-commit","title":"Hooks for <code>pre-commit</code>","text":"<p><code>pre-commit</code> is a powerful framework for managing git hooks in a centralized fashion. PDM already uses <code>pre-commit</code> hooks for its internal QA checks. PDM exposes also several hooks that can be run locally or in CI pipelines.</p>"},{"location":"usage/advanced/#export-requirementstxt","title":"Export <code>requirements.txt</code>","text":"<p>This hook wraps the command <code>pdm export</code> along with any valid argument. It can be used as a hook (e.g., for CI) to ensure that you are going to check in the codebase a <code>requirements.txt</code>, which reflects the actual content of <code>pdm lock</code>.</p> <pre><code># export python requirements\n- repo: https://github.com/pdm-project/pdm\nrev: 2.x.y # a PDM release exposing the hook\nhooks:\n- id: pdm-export\n# command arguments, e.g.:\nargs: ['-o', 'requirements.txt', '--without-hashes']\nfiles: ^pdm.lock$\n</code></pre>"},{"location":"usage/advanced/#check-pdmlock-is-up-to-date-with-pyprojecttoml","title":"Check <code>pdm.lock</code> is up to date with pyproject.toml","text":"<p>This hook wraps the command <code>pdm lock --check</code> along with any valid argument. It can be used as a hook (e.g., for CI) to ensure that whenever <code>pyproject.toml</code> has a dependency added/changed/removed, that <code>pdm.lock</code> is also up to date.</p> <pre><code>- repo: https://github.com/pdm-project/pdm\nrev: 2.x.y # a PDM release exposing the hook\nhooks:\n- id: pdm-lock-check\n</code></pre>"},{"location":"usage/advanced/#sync-current-working-set-with-pdmlock","title":"Sync current working set with <code>pdm.lock</code>","text":"<p>This hook wraps the command <code>pdm sync</code> along with any valid argument. It can be used as a hook to ensure that your current working set is synced with <code>pdm.lock</code> whenever you checkout or merge a branch. Add keyring to <code>additional_dependencies</code> if you want to use your systems credential store.</p> <pre><code>- repo: https://github.com/pdm-project/pdm\nrev: 2.x.y # a PDM release exposing the hook\nhooks:\n- id: pdm-sync\nadditional_dependencies:\n- keyring\n</code></pre>"},{"location":"usage/config/","title":"Configure the Project","text":"<p>PDM's <code>config</code> command works just like <code>git config</code>, except that <code>--list</code> isn't needed to show configurations.</p> <p>Show the current configurations:</p> <pre><code>pdm config\n</code></pre> <p>Get one single configuration:</p> <pre><code>pdm config pypi.url\n</code></pre> <p>Change a configuration value and store in home configuration:</p> <pre><code>pdm config pypi.url \"https://test.pypi.org/simple\"\n</code></pre> <p>By default, the configuration are changed globally, if you want to make the config seen by this project only, add a <code>--local</code> flag:</p> <pre><code>pdm config --local pypi.url \"https://test.pypi.org/simple\"\n</code></pre> <p>Any local configurations will be stored in <code>pdm.toml</code> under the project root directory.</p>"},{"location":"usage/config/#configuration-files","title":"Configuration files","text":"<p>The configuration files are searched in the following order:</p> <ol> <li><code>&lt;PROJECT_ROOT&gt;/pdm.toml</code> - The project configuration</li> <li><code>&lt;CONFIG_ROOT&gt;/config.toml</code> - The home configuration</li> <li><code>&lt;SITE_CONFIG_ROOT&gt;/config.toml</code> - The site configuration</li> </ol> <p>where <code>&lt;CONFIG_ROOT&gt;</code> is:</p> <ul> <li><code>$XDG_CONFIG_HOME/pdm</code> (<code>~/.config/pdm</code> in most cases) on Linux as defined by XDG Base Directory Specification</li> <li><code>~/Library/Application Support/pdm</code> on macOS as defined by Apple File System Basics</li> <li><code>%USERPROFILE%\\AppData\\Local\\pdm</code> on Windows as defined in Known folders</li> </ul> <p>and <code>&lt;SITE_CONFIG_ROOT&gt;</code> is:</p> <ul> <li><code>$XDG_CONFIG_DIRS/pdm</code> (<code>/etc/xdg/pdm</code> in most cases) on Linux as defined by XDG Base Directory Specification</li> <li><code>/Library/Application Support/pdm</code> on macOS as defined by Apple File System Basics</li> <li><code>C:\\ProgramData\\pdm\\pdm</code> on Windows as defined in Known folders</li> </ul> <p>If <code>-g/--global</code> option is used, the first item will be replaced by <code>&lt;CONFIG_ROOT&gt;/global-project/pdm.toml</code>.</p> <p>You can find all available configuration items in Configuration Page.</p>"},{"location":"usage/config/#configure-the-python-finder","title":"Configure the Python finder","text":"<p>By default, PDM will try to find Python interpreters in the following sources:</p> <ul> <li><code>venv</code>: The PDM virtualenv location</li> <li><code>path</code>: The <code>PATH</code> environment variable</li> <li><code>pyenv</code>: The pyenv install root</li> <li><code>rye</code>: The rye toolchain install root</li> <li><code>asdf</code>: The asdf python install root</li> <li><code>winreg</code>: The Windows registry</li> </ul> <p>You can unselect some of them or change the order by setting <code>python.providers</code> config key:</p> <pre><code>pdm config python.providers rye   # Rye source only\npdm config python.providers pyenv,asdf  # pyenv and asdf\n</code></pre>"},{"location":"usage/config/#allow-prereleases-in-resolution-result","title":"Allow prereleases in resolution result","text":"<p>By default, <code>pdm</code>'s dependency resolver will ignore prereleases unless there are no stable versions for the given version range of a dependency. This behavior can be changed by setting <code>allow-prereleases</code> to <code>true</code> in <code>[tool.pdm.resolution]</code> table:</p> <pre><code>[tool.pdm.resolution]\nallow-prereleases = true\n</code></pre>"},{"location":"usage/config/#configure-the-package-indexes","title":"Configure the package indexes","text":"<p>You can tell PDM where to to find the packages by either specifying sources in the <code>pyproject.toml</code> or via <code>pypi.*</code> configurations.</p> <p>Add sources in <code>pyproject.toml</code>:</p> <pre><code>[[tool.pdm.source]]\nname = \"private\"\nurl = \"https://private.pypi.org/simple\"\nverify_ssl = true\n</code></pre> <p>Change the default index via <code>pdm config</code>:</p> <pre><code>pdm config pypi.url \"https://test.pypi.org/simple\"\n</code></pre> <p>Add extra indexes via <code>pdm config</code>:</p> <pre><code>pdm config pypi.extra.url \"https://extra.pypi.org/simple\"\n</code></pre> <p>The available configuration options are:</p> <ul> <li><code>url</code>: The URL of the index</li> <li><code>verify_ssl</code>: (Optional)Whether to verify SSL certificates, default to true</li> <li><code>username</code>: (Optional)The username for the index</li> <li><code>password</code>: (Optional)The password for the index</li> <li><code>type</code>: (Optional) index or find_links, default to index</li> </ul> About the source types <p>By default, all sources are PEP 503 style \"indexes\" like pip's <code>--index-url</code> and <code>--extra-index-url</code>, however, you can set the type to <code>find_links</code> which contains files or links to be looked for directly. See this answer for the difference between the two types.</p> <p>These configurations are read in the following order to build the final source list:</p> <ul> <li><code>pypi.url</code>, if <code>pypi</code> doesn't appear in the <code>name</code> field of any source in <code>pyproject.toml</code></li> <li>Sources in <code>pyproject.toml</code></li> <li><code>pypi.&lt;name&gt;.url</code> in PDM config.</li> </ul> <p>You can set <code>pypi.ignore_stored_index</code> to <code>true</code> to disable all indexes from the PDM config and only use those specified in <code>pyproject.toml</code>.</p> <p>Disable the default PyPI index</p> <p>If you want to omit the default PyPI index, just set the source name to <code>pypi</code> and that source will replace it.</p> <pre><code>[[tool.pdm.source]]\nurl = \"https://private.pypi.org/simple\"\nverify_ssl = true\nname = \"pypi\"\n</code></pre> Indexes in <code>pyproject.toml</code> or config <p>When you want to share the indexes with other people who are going to use the project, you should add them in <code>pyproject.toml</code>. For example, some packages only exist in a private index and can't be installed if someone doesn't configure the index. Otherwise, store them in the local config which won't be seen by others.</p>"},{"location":"usage/config/#respect-the-order-of-the-sources","title":"Respect the order of the sources","text":"<p>By default, all sources are considered equal, packages from them are sorted by the version and wheel tags, the most matching one with the highest version is selected.</p> <p>In some cases you may want to return packages from the preferred source, and search for others if they are missing from the former source. PDM supports this by reading the configuration <code>respect-source-order</code>:</p> <pre><code>[tool.pdm.resolution]\nrespect-source-order = true\n</code></pre>"},{"location":"usage/config/#specify-index-for-individual-packages","title":"Specify index for individual packages","text":"<p>You can bind packages to specific sources with <code>include_packages</code> and <code>exclude_packages</code> config under <code>tool.pdm.source</code> table.</p> <pre><code>[[tool.pdm.source]]\nname = \"private\"\nurl = \"https://private.pypi.org/simple\"\ninclude_packages = [\"foo\", \"foo-*\"]\nexclude_packages = [\"bar-*\"]\n</code></pre> <p>With the above configuration, any package matching <code>foo</code> or <code>foo-*</code> will only be searched from the <code>private</code> index, and any package matching <code>bar-*</code> will be searched from all indexes except <code>private</code>.</p> <p>Both <code>include_packages</code> and <code>exclude_packages</code> are optional and accept a list of glob patterns, and <code>include_packages</code> takes effect exclusively when the pattern matches.</p>"},{"location":"usage/config/#store-credentials-with-the-index","title":"Store credentials with the index","text":"<p>You can specify credentials in the URL with <code>${ENV_VAR}</code> variable expansion and these variables will be read from the environment variables:</p> <pre><code>[[tool.pdm.source]]\nname = \"private\"\nurl = \"https://${PRIVATE_PYPI_USERNAME}:${PRIVATE_PYPI_PASSWORD}@private.pypi.org/simple\"\n</code></pre>"},{"location":"usage/config/#configure-https-certificates","title":"Configure HTTPS certificates","text":"<p>You can use a custom CA bundle or client certificate for HTTPS requests. It can be configured for both indexes(for package download) and repositories(for upload):</p> <pre><code>pdm config pypi.ca_certs /path/to/ca_bundle.pem\npdm config repository.pypi.ca_certs /path/to/ca_bundle.pem\n</code></pre> <p>Besides, it is possible to use the system trust store, instead of the bundled certifi certificates for verifying HTTPS certificates. This approach will typically support corporate proxy certificates without additional configuration.</p> <p>To use <code>truststore</code>, you need Python 3.10 or newer and install <code>truststore</code> into the same environment as PDM:</p> <pre><code>$ pdm self add truststore\n</code></pre>"},{"location":"usage/config/#index-configuration-merging","title":"Index configuration merging","text":"<p>Index configurations are merged with the <code>name</code> field of <code>[[tool.pdm.source]]</code> table or <code>pypi.&lt;name&gt;</code> key in the config file. This enables you to store the url and credentials separately, to avoid secrets being exposed in the source control. For example, if you have the following configuration:</p> <pre><code>[[tool.pdm.source]]\nname = \"private\"\nurl = \"https://private.pypi.org/simple\"\n</code></pre> <p>You can store the credentials in the config file:</p> <pre><code>pdm config pypi.private.username \"foo\"\npdm config pypi.private.password \"bar\"\n</code></pre> <p>PDM can retrieve the configurations for <code>private</code> index from both places.</p> <p>If the index requires a username and password, but they can't be found from the environment variables nor config file, PDM will prompt you to enter them. Or, if <code>keyring</code> is installed, it will be used as the credential store. PDM can use the <code>keyring</code> from either the installed package or the CLI.</p>"},{"location":"usage/config/#central-installation-caches","title":"Central installation caches","text":"<p>If a package is required by many projects on the system, each project has to keep its own copy. This can be a waste of disk space, especially for data science and machine learning projects.</p> <p>PDM supports caching installations of the same wheel by installing it in a centralized package repository and linking to that installation in different projects. To enable it, run:</p> <pre><code>pdm config install.cache on\n</code></pre> <p>It can be enabled on a per-project basis by adding the <code>--local</code> option to the command.</p> <p>The caches are located in <code>$(pdm config cache_dir)/packages</code>. You can view the cache usage with <code>pdm cache info</code>. Note that the cached installs are managed automatically -- they will be deleted if they are not linked to any projects. Manually deleting the caches from disk may break some projects on the system.</p> <p>In addition, several different ways of linking to cache entries are supported:</p> <ul> <li><code>symlink</code>(default), create symlinks to the package files.</li> <li><code>hardlink</code>, create hard links to the package files of the cache entry.</li> </ul> <p>You can switch between them by running <code>pdm config [-l] install.cache_method &lt;method&gt;</code>.</p> <p>Note</p> <p>Only the installation of named requirements resolved from PyPI can be cached.</p>"},{"location":"usage/config/#configure-the-repositories-for-upload","title":"Configure the repositories for upload","text":"<p>When using the <code>pdm publish</code> command, it reads the repository secrets from the global config file(<code>&lt;CONFIG_ROOT&gt;/config.toml</code>). The content of the config is as follows:</p> <pre><code>[repository.pypi]\nusername = \"frostming\"\npassword = \"&lt;secret&gt;\"\n\n[repository.company]\nurl = \"https://pypi.company.org/legacy/\"\nusername = \"frostming\"\npassword = \"&lt;secret&gt;\"\nca_certs = \"/path/to/custom-cacerts.pem\"\n</code></pre> <p>Alternatively, these credentials can be provided with env vars:</p> <pre><code>export PDM_PUBLISH_REPO=...\nexport PDM_PUBLISH_USERNAME=...\nexport PDM_PUBLISH_PASSWORD=...\nexport PDM_PUBLISH_CA_CERTS=...\n</code></pre> <p>A PEM-encoded Certificate Authority bundle (<code>ca_certs</code>) can be used for local / custom PyPI repositories where the server certificate is not signed by the standard certifi CA bundle.</p> <p>Note</p> <p>Repositories are different from indexes in the previous section. Repositories are for publishing while indexes are for locking and resolving. They don't share the configuration.</p> <p>Tip</p> <p>You don't need to configure the <code>url</code> for <code>pypi</code> and <code>testpypi</code> repositories, they are filled by default values. The username, password, and certificate authority bundle can be passed in from the command line for <code>pdm publish</code> via <code>--username</code>, <code>--password</code>, and <code>--ca-certs</code>, respectively.</p> <p>To change the repository config from the command line, use the <code>pdm config</code> command:</p> <pre><code>pdm config repository.pypi.username \"__token__\"\npdm config repository.pypi.password \"my-pypi-token\"\n\npdm config repository.company.url \"https://pypi.company.org/legacy/\"\npdm config repository.company.ca_certs \"/path/to/custom-cacerts.pem\"\n</code></pre>"},{"location":"usage/config/#password-management-with-keyring","title":"Password management with keyring","text":"<p>When keyring is available and supported, the passwords will be stored to and retrieved from the keyring instead of writing to the config file. This supports both indexes and upload repositories. The service name will be <code>pdm-pypi-&lt;name&gt;</code> for an index and <code>pdm-repository-&lt;name&gt;</code> for a repository.</p> <p>You can enable keyring by either installing <code>keyring</code> into the same environment as PDM or installing globally. To add keyring to the PDM environment:</p> <pre><code>pdm self add keyring\n</code></pre> <p>Alternatively, if you have installed a copy of keyring globally, make sure the CLI is exposed in the <code>PATH</code> env var to make it discoverable by PDM:</p> <pre><code>export PATH=$PATH:path/to/keyring/bin\n</code></pre>"},{"location":"usage/config/#override-the-resolved-package-versions","title":"Override the resolved package versions","text":"<p>Added in version 1.12.0</p> <p>Sometimes you can't get a dependency resolution due to incorrect version ranges set by upstream libraries that you can't fix. In this case you can use PDM's overrides feature to force a specific version of a package to be installed.</p> <p>Given the following configuration in <code>pyproject.toml</code>:</p> <pre><code>[tool.pdm.resolution.overrides]\nasgiref = \"3.2.10\"  # exact version\nurllib3 = \"&gt;=1.26.2\"  # version range\npytz = \"https://mypypi.org/packages/pytz-2020.9-py3-none-any.whl\"  # absolute URL\n</code></pre> <p>Each entry of that table is a package name with the wanted version. In this example, PDM will resolve the above packages into the given versions no matter whether there is any other resolution available.</p> <p>Warning</p> <p>By using <code>[tool.pdm.resolution.overrides]</code> setting, you are at your own risk of any incompatibilities from that resolution. It can only be used if there is no valid resolution for your requirements and you know the specific version works. Most of the time, you can just add any transient constraints to the <code>dependencies</code> array.</p>"},{"location":"usage/config/#exclude-specific-packages-and-their-dependencies-from-the-lock-file","title":"Exclude specific packages and their dependencies from the lock file","text":"<p>Added in version 2.12.0</p> <p>Sometimes you don't even want to include certain packages in the locked file because you are sure they won't be used by any code. In this case, you can completely skip them and their dependencies during dependency resolution:</p> <pre><code>[tool.pdm.resolution]\nexcludes = [\"requests\"]\n</code></pre> <p>With this config, <code>requests</code> will not be locked in the lockfile, and its dependencies such as <code>urllib3</code> and <code>idna</code> will also not show up in the resolution result, if not depended on by other packages. The installer will not be able to pick them up either.</p>"},{"location":"usage/config/#passing-constant-arguments-to-every-pdm-invocation","title":"Passing constant arguments to every pdm invocation","text":"<p>Added in version 2.7.0</p> <p>You can add extra options passed to individual pdm commands by <code>tool.pdm.options</code> configuration:</p> <pre><code>[tool.pdm.options]\nadd = [\"--no-isolation\", \"--no-self\"]\ninstall = [\"--no-self\"]\nlock = [\"--no-cross-platform\"]\n</code></pre> <p>These options will be added right after the command name. For instance, based on the configuration above, <code>pdm add requests</code> is equivalent to <code>pdm add --no-isolation --no-self requests</code>.</p>"},{"location":"usage/config/#ignore-package-warnings","title":"Ignore package warnings","text":"<p>Added in version 2.10.0</p> <p>You may see some warnings when resolving dependencies like this:</p> <pre><code>PackageWarning: Skipping scipy@1.10.0 because it requires Python\n&lt;3.12,&gt;=3.8 but the project claims to work with Python&gt;=3.9.\nNarrow down the `requires-python` range to include this version. For example, \"&gt;=3.9,&lt;3.12\" should work.\n  warnings.warn(record.message, PackageWarning, stacklevel=1)\nUse `-q/--quiet` to suppress these warnings, or ignore them per-package with `ignore_package_warnings` config in [tool.pdm] table.\n</code></pre> <p>This is because the supported range of Python versions of the package doesn't cover the <code>requires-python</code> value specified in the <code>pyproject.toml</code>. You can ignore these warnings in a per-package basis by adding the following config:</p> <pre><code>[tool.pdm]\nignore_package_warnings = [\"scipy\", \"tensorflow-*\"]\n</code></pre> <p>Where each item is a case-insensitive glob pattern to match the package name.</p>"},{"location":"usage/dependency/","title":"Manage Dependencies","text":"<p>PDM provides a bunch of handful commands to help manage your project and dependencies. The following examples are run on Ubuntu 18.04, a few changes must be done if you are using Windows.</p>"},{"location":"usage/dependency/#add-dependencies","title":"Add dependencies","text":"<p><code>pdm add</code> can be followed by one or several dependencies, and the dependency specification is described in PEP 508.</p> <p>Examples:</p> <pre><code>pdm add requests   # add requests\npdm add requests==2.25.1   # add requests with version constraint\npdm add requests[socks]   # add requests with extra dependency\npdm add \"flask&gt;=1.0\" flask-sqlalchemy   # add multiple dependencies with different specifiers\n</code></pre> <p>PDM also allows extra dependency groups by providing <code>-G/--group &lt;name&gt;</code> option, and those dependencies will go to <code>[project.optional-dependencies.&lt;name&gt;]</code> table in the project file, respectively.</p> <p>You can reference other optional groups in <code>optional-dependencies</code>, even before the package is uploaded:</p> <pre><code>[project]\nname = \"foo\"\nversion = \"0.1.0\"\n\n[project.optional-dependencies]\nsocks = [\"pysocks\"]\njwt = [\"pyjwt\"]\nall = [\"foo[socks,jwt]\"]\n</code></pre> <p>After that, dependencies and sub-dependencies will be resolved properly and installed for you, you can view <code>pdm.lock</code> to see the resolved result of all dependencies.</p>"},{"location":"usage/dependency/#local-dependencies","title":"Local dependencies","text":"<p>Local packages can be added with their paths. The path can be a file or a directory:</p> <pre><code>pdm add ./sub-package\npdm add ./first-1.0.0-py2.py3-none-any.whl\n</code></pre> <p>The paths MUST start with a <code>.</code>, otherwise it will be recognized as a normal named requirement. The local dependencies will be written to the <code>pyproject.toml</code> file with the URL format:</p> <pre><code>[project]\ndependencies = [\n\"sub-package @ file:///${PROJECT_ROOT}/sub-package\",\n\"first @ file:///${PROJECT_ROOT}/first-1.0.0-py2.py3-none-any.whl\",\n]\n</code></pre> Using other build backends <p>If you are using <code>hatchling</code> instead of the pdm backend, the URLs would be as follows:</p> <p><pre><code>sub-package @ {root:uri}/sub-package\nfirst @ {root:uri}/first-1.0.0-py2.py3-none-any.whl\n</code></pre> Other backends doesn't support encoding relative paths in the URL and will write the absolute path instead.</p>"},{"location":"usage/dependency/#url-dependencies","title":"URL dependencies","text":"<p>PDM also supports downloading and installing packages directly from a web address.</p> <p>Examples:</p> <pre><code># Install gzipped package from a plain URL\npdm add \"https://github.com/numpy/numpy/releases/download/v1.20.0/numpy-1.20.0.tar.gz\"\n# Install wheel from a plain URL\npdm add \"https://github.com/explosion/spacy-models/releases/download/en_core_web_trf-3.5.0/en_core_web_trf-3.5.0-py3-none-any.whl\"\n</code></pre>"},{"location":"usage/dependency/#vcs-dependencies","title":"VCS dependencies","text":"<p>You can also install from a git repository url or other version control systems. The following are supported:</p> <ul> <li>Git: <code>git</code></li> <li>Mercurial: <code>hg</code></li> <li>Subversion: <code>svn</code></li> <li>Bazaar: <code>bzr</code></li> </ul> <p>The URL should be like: <code>{vcs}+{url}@{rev}</code></p> <p>Examples:</p> <pre><code># Install pip repo on tag `22.0`\npdm add \"git+https://github.com/pypa/pip.git@22.0\"\n# Provide credentials in the URL\npdm add \"git+https://username:password@github.com/username/private-repo.git@master\"\n# Give a name to the dependency\npdm add \"pip @ git+https://github.com/pypa/pip.git@22.0\"\n# Or use the #egg fragment\npdm add \"git+https://github.com/pypa/pip.git@22.0#egg=pip\"\n# Install from a subdirectory\npdm add \"git+https://github.com/owner/repo.git@master#egg=pkg&amp;subdirectory=subpackage\"\n</code></pre>"},{"location":"usage/dependency/#hide-credentials-in-the-url","title":"Hide credentials in the URL","text":"<p>You can hide the credentials in the URL by using the <code>${ENV_VAR}</code> variable syntax:</p> <pre><code>[project]\ndependencies = [\n\"mypackage @ git+http://${VCS_USER}:${VCS_PASSWD}@test.git.com/test/mypackage.git@master\"\n]\n</code></pre> <p>These variables will be read from the environment variables when installing the project.</p>"},{"location":"usage/dependency/#add-development-only-dependencies","title":"Add development only dependencies","text":"<p>Added in version 1.5.0</p> <p>PDM also supports defining groups of dependencies that are useful for development, e.g. some for testing and others for linting. We usually don't want these dependencies appear in the distribution's metadata so using <code>optional-dependencies</code> is probably not a good idea. We can define them as development dependencies:</p> <pre><code>pdm add -dG test pytest\n</code></pre> <p>This will result in a pyproject.toml as following:</p> <pre><code>[tool.pdm.dev-dependencies]\ntest = [\"pytest\"]\n</code></pre> <p>You can have several groups of development only dependencies. Unlike <code>optional-dependencies</code>, they won't appear in the package distribution metadata such as <code>PKG-INFO</code> or <code>METADATA</code>. The package index won't be aware of these dependencies. The schema is similar to that of <code>optional-dependencies</code>, except that it is in <code>tool.pdm</code> table.</p> <p><pre><code>[tool.pdm.dev-dependencies]\nlint = [\n\"flake8\",\n\"black\"\n]\ntest = [\"pytest\", \"pytest-cov\"]\ndoc = [\"mkdocs\"]\n</code></pre> For backward-compatibility, if only <code>-d</code> or <code>--dev</code> is specified, dependencies will go to <code>dev</code> group under <code>[tool.pdm.dev-dependencies]</code> by default.</p> <p>Note</p> <p>The same group name MUST NOT appear in both <code>[tool.pdm.dev-dependencies]</code> and <code>[project.optional-dependencies]</code>.</p>"},{"location":"usage/dependency/#editable-dependencies","title":"Editable dependencies","text":"<p>Local directories and VCS dependencies can be installed in editable mode. If you are familiar with <code>pip</code>, it is just like <code>pip install -e &lt;package&gt;</code>. Editable packages are allowed only in development dependencies:</p> <p>Note</p> <p>Editable installs are only allowed in the <code>dev</code> dependency group. Other groups, including the default, will fail with a <code>[PdmUsageError]</code>.</p> <pre><code># A relative path to the directory\npdm add -e ./sub-package --dev\n# A file URL to a local directory\npdm add -e file:///path/to/sub-package --dev\n# A VCS URL\npdm add -e git+https://github.com/pallets/click.git@main#egg=click --dev\n</code></pre>"},{"location":"usage/dependency/#save-version-specifiers","title":"Save version specifiers","text":"<p>If the package is given without a version specifier like <code>pdm add requests</code>. PDM provides three different behaviors of what version specifier is saved for the dependency, which is given by <code>--save-&lt;strategy&gt;</code>(Assume <code>2.21.0</code> is the latest version that can be found for the dependency):</p> <ul> <li><code>minimum</code>: Save the minimum version specifier: <code>&gt;=2.21.0</code> (default).</li> <li><code>compatible</code>: Save the compatible version specifier: <code>&gt;=2.21.0,&lt;3.0.0</code>.</li> <li><code>exact</code>: Save the exact version specifier: <code>==2.21.0</code>.</li> <li><code>wildcard</code>: Don't constrain version and leave the specifier to be wildcard: <code>*</code>.</li> </ul>"},{"location":"usage/dependency/#add-prereleases","title":"Add prereleases","text":"<p>One can give <code>--pre/--prerelease</code> option to <code>pdm add</code> so that prereleases are allowed to be pinned for the given packages.</p>"},{"location":"usage/dependency/#update-existing-dependencies","title":"Update existing dependencies","text":"<p>To update all dependencies in the lock file:</p> <pre><code>pdm update\n</code></pre> <p>To update the specified package(s):</p> <pre><code>pdm update requests\n</code></pre> <p>To update multiple groups of dependencies:</p> <pre><code>pdm update -G security -G http\n</code></pre> <p>Or using comma-separated list:</p> <pre><code>pdm update -G \"security,http\"\n</code></pre> <p>To update a given package in the specified group:</p> <pre><code>pdm update -G security cryptography\n</code></pre> <p>If the group is not given, PDM will search for the requirement in the default dependencies set and raises an error if none is found.</p> <p>To update packages in development dependencies:</p> <pre><code># Update all default + dev-dependencies\npdm update -d\n# Update a package in the specified group of dev-dependencies\npdm update -dG test pytest\n</code></pre>"},{"location":"usage/dependency/#about-update-strategy","title":"About update strategy","text":"<p>Similarly, PDM also provides 3 different behaviors of updating dependencies and sub-dependencies\uff0c which is given by <code>--update-&lt;strategy&gt;</code> option:</p> <ul> <li><code>reuse</code>: Keep all locked dependencies except for those given in the command line (default).</li> <li><code>reuse-installed</code>: Try to reuse the versions installed in the working set. This will also affect the packages requested in the command line.</li> <li><code>eager</code>: Try to lock a newer version of the packages in command line and their recursive sub-dependencies and keep other dependencies as they are.</li> <li><code>all</code>: Update all dependencies and sub-dependencies.</li> </ul>"},{"location":"usage/dependency/#update-packages-to-the-versions-that-break-the-version-specifiers","title":"Update packages to the versions that break the version specifiers","text":"<p>One can give <code>-u/--unconstrained</code> to tell PDM to ignore the version specifiers in the <code>pyproject.toml</code>. This works similarly to the <code>yarn upgrade -L/--latest</code> command. Besides, <code>pdm update</code> also supports the <code>--pre/--prerelease</code> option.</p>"},{"location":"usage/dependency/#remove-existing-dependencies","title":"Remove existing dependencies","text":"<p>To remove existing dependencies from project file and the library directory:</p> <pre><code># Remove requests from the default dependencies\npdm remove requests\n# Remove h11 from the 'web' group of optional-dependencies\npdm remove -G web h11\n# Remove pytest-cov from the `test` group of dev-dependencies\npdm remove -dG test pytest-cov\n</code></pre>"},{"location":"usage/dependency/#install-the-packages-pinned-in-lock-file","title":"Install the packages pinned in lock file","text":"<p>There are a few similar commands to do this job with slight differences:</p> <ul> <li><code>pdm sync</code> installs packages from the lock file.</li> <li><code>pdm update</code> will update the lock file, then <code>sync</code>.</li> <li><code>pdm install</code> will check the project file for changes, update the lock file if needed, then <code>sync</code>.</li> </ul> <p><code>sync</code> also has a few options to manage installed packages:</p> <ul> <li><code>--clean</code>: will remove packages no longer in the lockfile</li> <li><code>--only-keep</code>: only selected packages (using options like <code>-G</code> or <code>--prod</code>) will be kept.</li> </ul>"},{"location":"usage/dependency/#specify-the-lockfile-to-use","title":"Specify the lockfile to use","text":"<p>You can specify another lockfile than the default <code>pdm lock</code> by using the <code>-L/--lockfile &lt;filepath&gt;</code> option or the <code>PDM_LOCKFILE</code> environment variable.</p>"},{"location":"usage/dependency/#select-a-subset-of-dependency-groups-to-be-installed-or-locked","title":"Select a subset of dependency groups to be installed or locked","text":"<p>Say we have a project with following dependencies:</p> <pre><code>[project]  # This is production dependencies\ndependencies = [\"requests\"]\n\n[project.optional-dependencies]  # This is optional dependencies\nextra1 = [\"flask\"]\nextra2 = [\"django\"]\n\n[tool.pdm.dev-dependencies]  # This is dev dependencies\ndev1 = [\"pytest\"]\ndev2 = [\"mkdocs\"]\n</code></pre> Command What it does Comments <code>pdm install</code> install all groups locked in the lockfile <code>pdm install -G extra1</code> install prod deps, dev deps, and \"extra1\" optional group <code>pdm install -G dev1</code> install prod deps and only \"dev1\" dev group <code>pdm install -G:all</code> install prod deps, dev deps and \"extra1\", \"extra2\" optional groups <code>pdm install -G extra1 -G dev1</code> install prod deps, \"extra1\" optional group and only \"dev1\" dev group <code>pdm install --prod</code> install prod only <code>pdm install --prod -G extra1</code> install prod deps and \"extra1\" optional <code>pdm install --prod -G dev1</code> Fail, <code>--prod</code> can't be given with dev dependencies Leave the <code>--prod</code> option <p>All development dependencies are included as long as <code>--prod</code> is not passed and <code>-G</code> doesn't specify any dev groups.</p> <p>Besides, if you don't want the root project to be installed, add <code>--no-self</code> option, and <code>--no-editable</code> can be used when you want all packages to be installed in non-editable versions.</p> <p>You may also use the pdm lock command with these options to lock only the specified groups, which will be recorded in the <code>[metadata]</code> table of the lock file. If no <code>--group/--prod/--dev/--no-default</code> option is specified, <code>pdm sync</code> and <code>pdm update</code> will operate using the groups in the lockfile. However, if any groups that are not included in the lockfile are given as arguments to the commands, PDM will raise an error.</p> <p>This feature is especially valuable when managing multiple lockfiles, where each may have different versions of the same package pinned. To switch between lockfiles, you can use the <code>--lockfile/-L</code> option.</p> <p>For a realistic example, your project depends on a release version of <code>werkzeug</code> and you may want to work with a local in-development copy of it when developing. You can add the following to your <code>pyproject.toml</code>:</p> <pre><code>[project]\nrequires-python = \"&gt;=3.7\"\ndependencies = [\"werkzeug\"]\n\n[tool.pdm.dev-dependencies]\ndev = [\"werkzeug @ file:///${PROJECT_ROOT}/dev/werkzeug\"]\n</code></pre> <p>Then, run <code>pdm lock</code> with different options to generate lockfiles for different purposes:</p> <pre><code># Lock default + dev, write to pdm.lock\n# with the local copy of werkzeug pinned.\npdm lock\n# Lock default, write to pdm.prod.lock\n# with the release version of werkzeug pinned.\npdm lock --prod -L pdm.prod.lock\n</code></pre> <p>Check the <code>metadata.groups</code> field in the lockfile to see which groups are included.</p>"},{"location":"usage/dependency/#lock-strategies","title":"Lock strategies","text":"<p>Currently, we support three flags to control the locking behavior: <code>cross_platform</code>, <code>static_urls</code> and <code>direct_minimal_versions</code>, with the meanings as follows. You can pass one or more flags to <code>pdm lock</code> by <code>--strategy/-S</code> option, either by giving a comma-separated list or by passing the option multiple times. Both of these commands function in the same way:</p> <pre><code>pdm lock -S cross_platform,static_urls\npdm lock -S cross_platform -S static_urls\n</code></pre> <p>The flags will be encoded in the lockfile and get read when you run <code>pdm lock</code> next time. But you can disable flags by prefixing the flag name with <code>no_</code>:</p> <pre><code>pdm lock -S no_cross_platform\n</code></pre> <p>This command makes the lockfile not cross-platform.</p>"},{"location":"usage/dependency/#cross-platform","title":"Cross platform","text":"<p>Added in version 2.6.0</p> <p>By default, the generated lockfile is cross-platform, which means the current platform isn't taken into account when resolving the dependencies. The result lockfile will contain wheels and dependencies for all possible platforms and Python versions. However, sometimes this will result in a wrong lockfile when a release doesn't contain all wheels. To avoid this, you can tell PDM to create a lockfile that works for this platform only, trimming the wheels not relevant to the current platform. This can be done by passing the <code>--strategy no_cross_platform</code> option to <code>pdm lock</code>:</p> <pre><code>pdm lock --strategy no_cross_platform\n</code></pre>"},{"location":"usage/dependency/#static-urls","title":"Static URLs","text":"<p>Added in version 2.8.0</p> <p>By default, PDM only stores the filenames of the packages in the lockfile, which benefits the reusability across different package indexes. However, if you want to store the static URLs of the packages in the lockfile, you can pass the <code>--strategy static_urls</code> option to <code>pdm lock</code>:</p> <pre><code>pdm lock --strategy static_urls\n</code></pre> <p>The settings will be saved and remembered for the same lockfile. You can also pass <code>--strategy no_static_urls</code> to disable it.</p>"},{"location":"usage/dependency/#direct-minimal-versions","title":"Direct minimal versions","text":"<p>Added in version 2.10.0</p> <p>When it is enabled by passing <code>--strategy direct_minimal_versions</code>, dependencies specified in the <code>pyproject.toml</code> will be resolved to the minimal versions available, rather than the latest versions. This is useful when you want to test the compatibility of your project within a range of dependency versions.</p> <p>For example, if you specified <code>flask&gt;=2.0</code> in the <code>pyproject.toml</code>, <code>flask</code> will be resolved to version <code>2.0.0</code> if there is no other compatibility issue.</p> <p>Note</p> <p>Version constraints in package dependencies are not future-proof. If you resolve the dependencies to the minimal versions, there will likely be backwards-compatibility issues. For example, <code>flask==2.0.0</code> requires <code>werkzeug&gt;=2.0</code>, but in fact, it can not work with <code>Werkzeug 3.0.0</code>, which is released 2 years after it.</p>"},{"location":"usage/dependency/#inherit-the-metadata-from-parents","title":"Inherit the metadata from parents","text":"<p>Added in version 2.11.0</p> <p>Previously, the <code>pdm lock</code> command would record package metadata as it is. When installing, PDM would start from the top requirements and traverse down to the leaf node of the dependency tree. It would then evaluate any marker it encounters against the current environment. If a marker is not satisfied, the package would be discarded. In other words, we need an additional \"resolution\" step in installation.</p> <p>When the <code>inherit_metadata</code> strategy is enabled, PDM will inherit and merge environment markers from a package's ancestors. These markers are then encoded in the lockfile during locking, resulting in faster installations. This has been enabled by default from version <code>2.11.0</code>, to disable this strategy in the config, use <code>pdm config strategy.inherit_metadata false</code>.</p>"},{"location":"usage/dependency/#exclude-packages-newer-than-specific-date","title":"Exclude packages newer than specific date","text":"<p>Added in version 2.13.0</p> <p>You can exclude packages that are newer than a specified date by passing the <code>--exclude-newer</code> option to <code>pdm lock</code>. This is useful when you want to lock the dependencies to a specific date, for example, to ensure reproducibility of the build.</p> <p>The date may be specified as a RFC 3339 timestamp (e.g., <code>2006-12-02T02:07:43Z</code>) or UTC date in the same format (e.g., <code>2006-12-02</code>).</p> <pre><code>pdm lock --exclude-newer 2024-01-01\n</code></pre> <p>Note</p> <p>The package index must support the <code>upload-time</code> field as specified in PEP 700. If the field is not present for a given distribution, the distribution will be treated as unavailable.</p>"},{"location":"usage/dependency/#show-what-packages-are-installed","title":"Show what packages are installed","text":"<p>Similar to <code>pip list</code>, you can list all packages installed in the packages directory:</p> <pre><code>pdm list\n</code></pre>"},{"location":"usage/dependency/#include-and-exclude-groups","title":"Include and exclude groups","text":"<p>By default, all packages installed in the working set will be listed. You can specify which groups to be listed by <code>--include/--exclude</code> options, and <code>include</code> has a higher priority than <code>exclude</code>.</p> <pre><code>pdm list --include dev\npdm list --exclude test\n</code></pre> <p>There is a special group <code>:sub</code>, when included, all transitive dependencies will also be shown. It is included by default.</p> <p>You can also pass <code>--resolve</code> to <code>pdm list</code>, which will show the packages resolved in <code>pdm.lock</code>, rather than installed in the working set.</p>"},{"location":"usage/dependency/#change-the-output-fields-and-format","title":"Change the output fields and format","text":"<p>By default, name, version and location will be shown in the list output, you can view more fields or specify the order of fields by <code>--fields</code> option:</p> <pre><code>pdm list --fields name,licenses,version\n</code></pre> <p>For all supported fields, please refer to the CLI reference.</p> <p>Also, you can specify the output format other than the default table output. The supported formats and options are <code>--csv</code>, <code>--json</code>, <code>--markdown</code> and <code>--freeze</code>.</p>"},{"location":"usage/dependency/#show-the-dependency-tree","title":"Show the dependency tree","text":"<p>Or show a dependency tree by:</p> <pre><code>$ pdm list --tree\ntempenv 0.0.0\n\u2514\u2500\u2500 click 7.0 [ required: &lt;7.0.0,&gt;=6.7 ]\nblack 19.10b0\n\u251c\u2500\u2500 appdirs 1.4.3 [ required: Any ]\n\u251c\u2500\u2500 attrs 19.3.0 [ required: &gt;=18.1.0 ]\n\u251c\u2500\u2500 click 7.0 [ required: &gt;=6.5 ]\n\u251c\u2500\u2500 pathspec 0.7.0 [ required: &lt;1,&gt;=0.6 ]\n\u251c\u2500\u2500 regex 2020.2.20 [ required: Any ]\n\u251c\u2500\u2500 toml 0.10.0 [ required: &gt;=0.9.4 ]\n\u2514\u2500\u2500 typed-ast 1.4.1 [ required: &gt;=1.4.0 ]\nbump2version 1.0.0\n</code></pre> <p>Note that <code>--fields</code> option doesn't work with <code>--tree</code>.</p>"},{"location":"usage/dependency/#filter-packages-by-patterns","title":"Filter packages by patterns","text":"<p>You can also limit the packages to show by passing the patterns to <code>pdm list</code>:</p> <pre><code>pdm list flask-* requests-*\n</code></pre> Be careful with the shell expansion <p>In most shells, the wildcard <code>*</code> will be expanded if there are matching files under the current directory. To avoid getting unexpected results, you can wrap the patterns with single quotes: <code>pdm list 'flask-*' 'requests-*'</code>.</p> <p>In <code>--tree</code> mode, only the subtree of the matched packages will be displayed. This can be used to achieve the same purpose as <code>pnpm why</code>, which is to show why a specific package is required.</p> <pre><code>$ pdm list --tree --reverse certifi\ncertifi 2023.7.22\n\u2514\u2500\u2500 requests 2.31.0 [ requires: &gt;=2017.4.17 ]\n\u2514\u2500\u2500 cachecontrol[filecache] 0.13.1 [ requires: &gt;=2.16.0 ]\n</code></pre>"},{"location":"usage/dependency/#allow-prerelease-versions-to-be-installed","title":"Allow prerelease versions to be installed","text":"<p>Include the following setting in <code>pyproject.toml</code> to enable:</p> <pre><code>[tool.pdm.resolution]\nallow-prereleases = true\n</code></pre>"},{"location":"usage/dependency/#set-acceptable-format-for-locking-or-installing","title":"Set acceptable format for locking or installing","text":"<p>If you want to control the format(binary/sdist) of the packages, you can set the env vars <code>PDM_NO_BINARY</code> and <code>PDM_ONLY_BINARY</code>.</p> <p>Each env var is a comma-separated list of package name. You can set it to <code>:all:</code> to apply to all packages. For example:</p> <pre><code># No binary for werkzeug will be locked nor used for installation\nPDM_NO_BINARY=werkzeug pdm add flask\n# Only binaries will be locked in the lock file\nPDM_ONLY_BINARY=:all: pdm lock\n# No binaries will be used for installation\nPDM_NO_BINARY=:all: pdm install\n# Prefer binary distributions and even if sdist with higher version is available\nPDM_PREFER_BINARY=flask pdm install\n</code></pre>"},{"location":"usage/dependency/#solve-the-locking-failure","title":"Solve the locking failure","text":"<p>If PDM is not able to find a resolution to satisfy the requirements, it will raise an error. For example,</p> <pre><code>pdm django==3.1.4 \"asgiref&lt;3\"\n...\n\ud83d\udd12 Lock failed\nUnable to find a resolution for asgiref because of the following conflicts:\n  asgiref&lt;3 (from project)\nasgiref&lt;4,&gt;=3.2.10 (from &lt;Candidate django 3.1.4 from https://pypi.org/simple/django/&gt;)\nTo fix this, you could loosen the dependency version constraints in pyproject.toml. If that is not possible, you could also override the resolved version in `[tool.pdm.resolution.overrides]` table.\n</code></pre> <p>You can either change to a lower version of <code>django</code> or remove the upper bound of <code>asgiref</code>. But if it is not eligible for your project, you can try overriding the resolved package versions or even don't lock that specific package in <code>pyproject.toml</code>.</p>"},{"location":"usage/dependency/#manage-global-project","title":"Manage global project","text":"<p>Sometimes users may want to keep track of the dependencies of global Python interpreter as well. It is easy to do so with PDM, via <code>-g/--global</code> option which is supported by most subcommands.</p> <p>If the option is passed, <code>&lt;CONFIG_ROOT&gt;/global-project</code> will be used as the project directory, which is almost the same as normal project except that <code>pyproject.toml</code> will be created automatically for you and it doesn't support build features. The idea is taken from Haskell's stack.</p> <p>However, unlike <code>stack</code>, by default, PDM won't use global project automatically if a local project is not found. Users should pass <code>-g/--global</code> explicitly to activate it, since it is not very pleasing if packages go to a wrong place. But PDM also leave the decision to users, just set the config <code>global_project.fallback</code> to <code>true</code>.</p> <p>By default, when <code>pdm</code> uses global project implicitly the following message is printed: <code>Project is not found, fallback to the global project</code>. To disable this message set the config <code>global_project.fallback_verbose</code> to <code>false</code>.</p> <p>If you want global project to track another project file other than <code>&lt;CONFIG_ROOT&gt;/global-project</code>, you can provide the project path via <code>-p/--project &lt;path&gt;</code> option. Especially if you pass <code>--global --project .</code>, PDM will install the dependencies of the current project into the global Python.</p> <p>Warning</p> <p>Be careful with <code>remove</code> and <code>sync --clean/--pure</code> commands when global project is used, because it may remove packages installed in your system Python.</p>"},{"location":"usage/dependency/#export-locked-packages-to-alternative-formats","title":"Export locked packages to alternative formats","text":"<p>You can also export <code>pdm lock</code> to other formats, to ease the CI flow or image building process. Currently, only <code>requirements.txt</code> format is supported:</p> <pre><code>pdm export -o requirements.txt\n</code></pre> <p>Note</p> <p>You can also run <code>pdm export</code> with a <code>.pre-commit</code> hook.</p>"},{"location":"usage/hooks/","title":"Lifecycle and Hooks","text":"<p>As any Python deliverable, your project will go through the different phases of a Python project lifecycle and PDM provides commands to perform the expected tasks for those phases.</p> <p>It also provides hooks attached to these steps allowing for:</p> <ul> <li>plugins to listen to the signals of the same name.</li> <li>developers to define custom scripts with the same name.</li> </ul> <p>Besides, <code>pre_invoke</code> signal is emitted before ANY command is invoked, allowing plugins to modify the project or options beforehand.</p> <p>The built-in commands are currently split into 3 groups:</p> <ul> <li>the initialization phase</li> <li>the dependencies management.</li> <li>the publication phase.</li> </ul> <p>You will most probably need to perform some recurrent tasks between the installation and publication phases (housekeeping, linting, testing, ...) this is why PDM lets you define your own tasks/phases using user scripts.</p> <p>To provides full flexibility, PDM allows to skip some hooks and tasks on demand.</p>"},{"location":"usage/hooks/#initialization","title":"Initialization","text":"<p>The initialization phase should occur only once in a project lifetime by running the <code>pdm init</code> command to initialize an existing project (prompt to fill the <code>pyproject.toml</code> file).</p> <p>They trigger the following hooks:</p> <ul> <li><code>post_init</code></li> </ul> <pre><code>flowchart LR\n  subgraph pdm-init [pdm init]\n    direction LR\n    post-init{{Emit post_init}}\n    init --&gt; post-init\n  end</code></pre>"},{"location":"usage/hooks/#dependencies-management","title":"Dependencies management","text":"<p>The dependencies management is required for the developer to be able to work and perform the following:</p> <ul> <li><code>lock</code>: compute a lock file from the <code>pyproject.toml</code> requirements.</li> <li><code>sync</code>: synchronize (add/remove/update) PEP582 packages from the lock file and install the current project as editable.</li> <li><code>add</code>: add a dependency</li> <li><code>remove</code>: remove a dependency</li> </ul> <p>All those steps are directly available with the following commands:</p> <ul> <li><code>pdm lock</code>: execute the <code>lock</code> task</li> <li><code>pdm sync</code>: execute the <code>sync</code> task</li> <li><code>pdm install</code>: execute the <code>sync</code> task, preceded from <code>lock</code> if required</li> <li><code>pdm add</code>: add a dependency requirement, re-lock and then sync</li> <li><code>pdm remove</code>: remove a dependency requirement, re-lock and then sync</li> <li><code>pdm update</code>: re-lock dependencies from their latest versions and then sync</li> </ul> <p>They trigger the following hooks:</p> <ul> <li><code>pre_install</code></li> <li><code>post_install</code></li> <li><code>pre_lock</code></li> <li><code>post_lock</code></li> </ul> <pre><code>flowchart LR\n  subgraph pdm-install [pdm install]\n    direction LR\n\n    subgraph pdm-lock [pdm lock]\n      direction TB\n      pre-lock{{Emit pre_lock}}\n      post-lock{{Emit post_lock}}\n      pre-lock --&gt; lock --&gt; post-lock\n    end\n\n    subgraph pdm-sync [pdm sync]\n      direction TB\n      pre-install{{Emit pre_install}}\n      post-install{{Emit post_install}}\n      pre-install --&gt; sync --&gt; post-install\n    end\n\n    pdm-lock --&gt; pdm-sync\n  end</code></pre>"},{"location":"usage/hooks/#switching-python-version","title":"Switching Python version","text":"<p>This is a special case in dependency management: you can switch the current Python version using <code>pdm use</code> and it will emit the <code>post_use</code> signal with the new Python interpreter.</p> <pre><code>flowchart LR\n  subgraph pdm-use [pdm use]\n    direction LR\n    post-use{{Emit post_use}}\n    use --&gt; post-use\n  end</code></pre>"},{"location":"usage/hooks/#publication","title":"Publication","text":"<p>As soon as you are ready to publish your package/library, you will require the publication tasks:</p> <ul> <li><code>build</code>: build/compile assets requiring it and package everything into a Python package (sdist, wheel)</li> <li><code>upload</code>: upload/publish the package to a remote PyPI index</li> </ul> <p>All those steps are available with the following commands:</p> <ul> <li><code>pdm build</code></li> <li><code>pdm publish</code></li> </ul> <p>They trigger the following hooks:</p> <ul> <li><code>pre_publish</code></li> <li><code>post_publish</code></li> <li><code>pre_build</code></li> <li><code>post_build</code></li> </ul> <pre><code>flowchart LR\n  subgraph pdm-publish [pdm publish]\n    direction LR\n    pre-publish{{Emit pre_publish}}\n    post-publish{{Emit post_publish}}\n\n    subgraph pdm-build [pdm build]\n      pre-build{{Emit pre_build}}\n      post-build{{Emit post_build}}\n      pre-build --&gt; build --&gt; post-build\n    end\n\n    %% subgraph pdm-upload [pdm upload]\n    %%   pre-upload{{Emit pre_upload}}\n    %%   post-upload{{Emit post_upload}}\n    %%   pre-upload --&gt; upload --&gt; post-upload\n    %% end\n\n    pre-publish --&gt; pdm-build --&gt; upload --&gt; post-publish\n  end</code></pre> <p>Execution will stop at first failure, hooks included.</p>"},{"location":"usage/hooks/#user-scripts","title":"User scripts","text":"<p>User scripts are detailed in their own section but you should know that:</p> <ul> <li>each user script can define a <code>pre_*</code> and <code>post_*</code> script, including composite scripts.</li> <li>each <code>run</code> execution will trigger the <code>pre_run</code> and <code>post_run</code> hooks</li> <li>each script execution will trigger the <code>pre_script</code> and <code>post_script</code> hooks</li> </ul> <p>Given the following <code>scripts</code> definition:</p> <pre><code>[tool.pdm.scripts]\npre_script = \"\"\npost_script = \"\"\npre_test = \"\"\npost_test = \"\"\ntest = \"\"\npre_composite = \"\"\npost_composite = \"\"\ncomposite = {composite = [\"test\"]}\n</code></pre> <p>a <code>pdm run test</code> will have the following lifecycle:</p> <pre><code>flowchart LR\n  subgraph pdm-run-test [pdm run test]\n    direction LR\n    pre-run{{Emit pre_run}}\n    post-run{{Emit post_run}}\n    subgraph run-test [test task]\n      direction TB\n      pre-script{{Emit pre_script}}\n      post-script{{Emit post_script}}\n      pre-test[Execute pre_test]\n      post-test[Execute post_test]\n      test[Execute test]\n\n      pre-script --&gt; pre-test --&gt; test --&gt; post-test --&gt; post-script\n    end\n\n    pre-run --&gt; run-test --&gt; post-run\n  end</code></pre> <p>while <code>pdm run composite</code> will have the following:</p> <pre><code>flowchart LR\n  subgraph pdm-run-composite [pdm run composite]\n    direction LR\n    pre-run{{Emit pre_run}}\n    post-run{{Emit post_run}}\n\n    subgraph run-composite [composite task]\n      direction TB\n      pre-script-composite{{Emit pre_script}}\n      post-script-composite{{Emit post_script}}\n      pre-composite[Execute pre_composite]\n      post-composite[Execute post_composite]\n\n      subgraph run-test [test task]\n        direction TB\n        pre-script-test{{Emit pre_script}}\n        post-script-test{{Emit post_script}}\n        pre-test[Execute pre_test]\n        post-test[Execute post_test]\n\n        pre-script-test --&gt; pre-test --&gt; test --&gt; post-test --&gt; post-script-test\n      end\n\n      pre-script-composite --&gt; pre-composite --&gt; run-test --&gt; post-composite --&gt; post-script-composite\n    end\n\n     pre-run --&gt; run-composite --&gt; post-run\n  end</code></pre>"},{"location":"usage/hooks/#skipping","title":"Skipping","text":"<p>It is possible to control which task and hook runs for any built-in command as well as custom user scripts using the <code>--skip</code> option.</p> <p>It accepts a comma-separated list of hooks/task names to skip as well as the predefined <code>:all</code>, <code>:pre</code> and <code>:post</code> shortcuts respectively skipping all hooks, all <code>pre_*</code> hooks and all <code>post_*</code> hooks. You can also provide the skip list in <code>PDM_SKIP_HOOKS</code> environment variable but it will be overridden as soon as the <code>--skip</code> parameter is provided.</p> <p>Given the previous script block, running <code>pdm run --skip=:pre,post_test composite</code> will result in the following reduced lifecycle:</p> <pre><code>flowchart LR\n  subgraph pdm-run-composite [pdm run composite]\n    direction LR\n    post-run{{Emit post_run}}\n\n    subgraph run-composite [composite task]\n      direction TB\n      post-script-composite{{Emit post_script}}\n      post-composite[Execute post_composite]\n\n      subgraph run-test [test task]\n        direction TB\n        post-script-test{{Emit post_script}}\n\n        test --&gt; post-script-test\n      end\n\n      run-test --&gt; post-composite --&gt; post-script-composite\n    end\n\n     run-composite --&gt; post-run\n  end</code></pre>"},{"location":"usage/pep582/","title":"Working with PEP 582","text":"<p>PEP 582 has been rejected</p> <p>This is a rejected PEP. However, due to the fact that this feature is the reason for PDM's birth, PDM will retain the support. We recommend using virtual environments instead.</p> <p>With PEP 582, dependencies will be installed into <code>__pypackages__</code> directory under the project root. With PEP 582 enabled globally, you can also use the project interpreter to run scripts directly.</p> <p>When the project interpreter is a normal Python, this mode is enabled.</p> <p>Besides, on a project you work with for the first time on your machine, if it contains an empty <code>__pypackages__</code> directory, PEP 582 is enabled automatically, and virtualenv won't be created.</p>"},{"location":"usage/pep582/#enable-pep-582-globally","title":"Enable PEP 582 globally","text":"<p>To make the Python interpreters aware of PEP 582 packages, one need to add the <code>pdm/pep582/sitecustomize.py</code> to the Python library search path.</p> WindowsMac and Linux <p>One just needs to execute <code>pdm --pep582</code>, then environment variable will be changed automatically. Don't forget to restart the terminal session to take effect.</p> <p>The command to change the environment variables can be printed by <code>pdm --pep582 [&lt;SHELL&gt;]</code>. If <code>&lt;SHELL&gt;</code> isn't given, PDM will pick one based on some guesses. You can run <code>eval \"$(pdm --pep582)\"</code> to execute the command.</p> <p>You may want to write a line in your <code>.bash_profile</code>(or similar profiles) to make it effective when logging in. For example, in bash you can do this:</p> <pre><code>pdm --pep582 &gt;&gt; ~/.bash_profile\n</code></pre> <p>Once again, Don't forget to restart the terminal session to take effect.</p> How is it done? <p>Thanks to the site packages loading on Python startup. It is possible to patch the <code>sys.path</code> by executing the <code>sitecustomize.py</code> shipped with PDM. The interpreter can search the directories for the nearest <code>__pypackage__</code> folder and append it to the <code>sys.path</code> variable.</p>"},{"location":"usage/pep582/#configure-ide-to-support-pep-582","title":"Configure IDE to support PEP 582","text":"<p>Now there are no built-in support or plugins for PEP 582 in most IDEs, you have to configure your tools manually.</p>"},{"location":"usage/pep582/#pycharm","title":"PyCharm","text":"<p>Mark <code>__pypackages__/&lt;major.minor&gt;/lib</code> as Sources Root. Then, select as Python interpreter a Python installation with the same <code>&lt;major.minor&gt;</code> version.</p> <p>Additionally, if you want to use tools from the environment (e.g. <code>pytest</code>), you have to add the <code>__pypackages__/&lt;major.minor&gt;/bin</code> directory to the <code>PATH</code> variable in the corresponding run/debug configuration.</p>"},{"location":"usage/pep582/#vscode","title":"VSCode","text":"<p>Add the following two entries to the top-level dict in <code>.vscode/settings.json</code>:</p> <pre><code>{\n\"python.autoComplete.extraPaths\": [\"__pypackages__/&lt;major.minor&gt;/lib\"],\n\"python.analysis.extraPaths\": [\"__pypackages__/&lt;major.minor&gt;/lib\"]\n}\n</code></pre> <p>This file can be auto-generated with plugin <code>pdm-vscode</code>.</p> <p>Enable PEP582 globally, and make sure VSCode runs using the same user and shell you enabled PEP582 for.</p> Cannot enable PEP582 globally? <p>If for some reason you cannot enable PEP582 globally, you can still configure each \"launch\" in each project: set the <code>PYTHONPATH</code> environment variable in your launch configuration, in <code>.vscode/launch.json</code>. For example, to debug your <code>pytest</code> run:</p> <pre><code>{\n\"version\": \"0.2.0\",\n\"configurations\": [\n{\n\"name\": \"pytest\",\n\"type\": \"python\",\n\"request\": \"launch\",\n\"module\": \"pytest\",\n\"args\": [\"tests\"],\n\"justMyCode\": false,\n\"env\": {\"PYTHONPATH\": \"__pypackages__/&lt;major.minor&gt;/lib\"}\n}\n]\n}\n</code></pre> <p>If your package resides in a <code>src</code> directory, add it to <code>PYTHONPATH</code> as well:</p> <pre><code>\"env\": {\"PYTHONPATH\": \"src:__pypackages__/&lt;major.minor&gt;/lib\"}\n</code></pre> Using Pylance/Pyright? <p>If you have configured <code>\"python.analysis.diagnosticMode\": \"workspace\"</code>, and you see a ton of errors/warnings as a result. you may need to create <code>pyrightconfig.json</code> in the workspace directory, and fill in the following fields:</p> <pre><code>{\n\"exclude\": [\"__pypackages__\"]\n}\n</code></pre> <p>Then restart the language server or VS Code and you're good to go. In the future (microsoft/pylance-release#1150), maybe the problem will be solved.</p> Using Jupyter Notebook? <p>If you wish to use pdm to install jupyter notebook and use it in vscode in conjunction with the python extension:</p> <ol> <li>Use <code>pdm add notebook</code> or so to install notebook</li> <li>Add a <code>.env</code> file inside of your project directory with contents like the following:</li> </ol> <pre><code>PYTHONPATH=/your-workspace-path/__pypackages__/&lt;major&gt;.&lt;minor&gt;/lib\n</code></pre> <p>If the above still doesn't work, it's most likely because the environment variable is not properly loaded when the Notebook starts. There are two workarounds.</p> <ol> <li>Run <code>code .</code> in Terminal. It will open a new VSCode window in the current directory with the path set correctly. Use the Jupyter Notebook in the new window</li> <li>If you prefer not to open a new window, run the following at the beginning of your Jupyter Notebook to explicitly set the path:</li> </ol> <pre><code>import sys\nsys.path.append('/your-workspace-path/__pypackages__/&lt;major&gt;.&lt;minor&gt;/lib')\n</code></pre> <p>Reference Issue</p> PDM Task Provider <p>In addition, there is a VSCode Task Provider extension available for download.</p> <p>This makes it possible for VSCode to automatically detect pdm scripts so they can be run natively as VSCode Tasks.</p>"},{"location":"usage/pep582/#neovim","title":"Neovim","text":"<p>If using neovim-lsp with pyright and want your <code>__pypackages__</code> directory to be added to the path, you can add this to your project's <code>pyproject.toml</code>.</p> <pre><code>[tool.pyright]\nextraPaths = [\"__pypackages__/&lt;major.minor&gt;/lib/\"]\n</code></pre>"},{"location":"usage/pep582/#emacs","title":"Emacs","text":"<p>You have a few options, but basically you'll want to tell an LSP client to add <code>__pypackages__</code> to the paths it looks at. Here are a few options that are available:</p>"},{"location":"usage/pep582/#using-pyprojecttoml-and-pyright","title":"Using <code>pyproject.toml</code> and pyright","text":"<p>Add this to your project's <code>pyproject.toml</code>:</p> <pre><code>[tool.pyright]\nextraPaths = [\"__pypackages__/&lt;major.minor&gt;/lib/\"]\n</code></pre>"},{"location":"usage/pep582/#eglot-pyright","title":"eglot + pyright","text":"<p>Using pyright and eglot (included in Emacs 29), add the following to your config:</p> <pre><code>(defun get-pdm-packages-path ()\n\"For the current PDM project, find the path to the packages.\"\n(let ((packages-path (string-trim (shell-command-to-string \"pdm info --packages\"))))\n(concat packages-path \"/lib\")))\n\n(defun my/eglot-workspace-config (server)\n\"For the current PDM project, dynamically generate a python lsp config.\"\n`(:python\\.analysis (:extraPaths ,(vector (get-pdm-packages-path)))))\n\n(setq-default eglot-workspace-configuration #'my/eglot-workspace-config)\n</code></pre> <p>You'll want pyright installed either globally, or in your project (probably as a dev dependency). You can add this with, for example:</p> <pre><code>pdm add --dev --group devel pyright\n</code></pre>"},{"location":"usage/pep582/#lsp-mode-lsp-python-ms","title":"LSP-Mode + lsp-python-ms","text":"<p>Below is a sample code snippet showing how to make PDM work with lsp-python-ms in Emacs. Contributed by @linw1995.</p> <pre><code>  ;; TODO: Cache result\n(defun linw1995/pdm-get-python-executable (&amp;optional dir)\n(let ((pdm-get-python-cmd \"pdm info --python\"))\n(string-trim\n(shell-command-to-string\n(if dir\n(concat \"cd \"\ndir\n\" &amp;&amp; \"\npdm-get-python-cmd)\npdm-get-python-cmd)))))\n\n(defun linw1995/pdm-get-packages-path (&amp;optional dir)\n(let ((pdm-get-packages-cmd \"pdm info --packages\"))\n(concat (string-trim\n(shell-command-to-string\n(if dir\n(concat \"cd \"\ndir\n\" &amp;&amp; \"\npdm-get-packages-cmd)\npdm-get-packages-cmd)))\n\"/lib\")))\n\n(use-package lsp-python-ms\n:ensure t\n:init (setq lsp-python-ms-auto-install-server t)\n:hook (python-mode\n. (lambda ()\n(setq lsp-python-ms-python-executable (linw1995/pdm-get-python-executable))\n(setq lsp-python-ms-extra-paths (vector (linw1995/pdm-get-packages-path)))\n(require 'lsp-python-ms)\n(lsp))))  ; or lsp-deferred\n</code></pre>"},{"location":"usage/project/","title":"New Project","text":"<p>To start with, create a new project with <code>pdm init</code>:</p> <pre><code>mkdir my-project &amp;&amp; cd my-project\npdm init\n</code></pre> <p>You will need to answer a few questions, to help PDM to create a <code>pyproject.toml</code> file for you. For more usages of <code>pdm init</code>, please read Create your project from a template.</p>"},{"location":"usage/project/#choose-a-python-interpreter","title":"Choose a Python interpreter","text":"<p>At first, you need to choose a Python interpreter from a list of Python versions installed on your machine. The interpreter path will be stored in <code>.pdm-python</code> and used by subsequent commands. You can also change it later with <code>pdm use</code>.</p> <p>Alternatively, you can specify the Python interpreter path via <code>PDM_PYTHON</code> environment variable. When it is set, the path saved in <code>.pdm-python</code> will be ignored.</p>"},{"location":"usage/project/#virtualenv-or-not","title":"Virtualenv or not","text":"<p>After you select the Python interpreter, PDM will ask you whether you want to create a virtual environment for the project. If you choose yes, PDM will create a virtual environment in the project root directory, and use it as the Python interpreter for the project.</p> <p>If the selected Python interpreter is in a virtual environment, PDM will use it as the project environment and install dependencies into it. Otherwise, <code>__pypackages__</code> will be created in the project root and dependencies will be installed into it.</p> <p>For the difference between these two approaches, please refer to the corresponding sections in the docs:</p> <ul> <li>Virtualenv</li> <li><code>__pypackages__</code>(PEP 582)</li> </ul>"},{"location":"usage/project/#library-or-application","title":"Library or Application","text":"<p>A library and an application differ in many ways. In short, a library is a package that is intended to be installed and used by other projects. In most cases it also needs to be uploaded to PyPI. An application, on the other hand, is one that is directly facing end users and may need to be deployed into some production environments.</p> <p>In PDM, if you choose to create a library, PDM will add a <code>name</code>, <code>version</code> field to the <code>pyproject.toml</code> file, as well as a <code>[build-system]</code> table for the build backend, which is only useful if your project needs to be built and distributed. So you need to manually add these fields to <code>pyproject.toml</code> if you want to change the project from an application to a library. Also, a library project will be installed into the environment when you run <code>pdm install</code> or <code>pdm sync</code>, unless <code>--no-self</code> is specified.</p>"},{"location":"usage/project/#set-requires-python-value","title":"Set <code>requires-python</code> value","text":"<p>You need to set an appropriate <code>requires-python</code> value for your project. This is an important property that affects how dependencies are resolved. Basically, each package's <code>requires-python</code> must cover the project's <code>requires-python</code> range. For example, consider the following setup:</p> <ul> <li>Project: <code>requires-python = \"&gt;=3.9\"</code></li> <li>Package <code>foo</code>: <code>requires-python = \"&gt;=3.7,&lt;3.11\"</code></li> </ul> <p>Resolving the dependencies will cause a <code>ResolutionImpossible</code>:</p> <pre><code>Unable to find a resolution because the following dependencies don't work\non all Python versions defined by the project's `requires-python`\n</code></pre> <p>Because the dependency's <code>requires-python</code> is <code>&gt;=3.7,&lt;3.11</code>, it doesn't cover the project's <code>requires-python</code> range of <code>&gt;=3.9</code>. In other words, the project promises to work on Python 3.9, 3.10, 3.11 (and so on), but the dependency doesn't support Python 3.11 (or any higher). Since PDM creates a cross-platform lockfile that should work on all Python versions within the <code>requires-python</code> range, it can't find a valid resolution. To fix this, you need add a maximum version to <code>requires-python</code>, like <code>&gt;=3.9,&lt;3.11</code>.</p> <p>The value of <code>requires-python</code> is a version specifier as defined in PEP 440. Here are some examples:</p> <code>requires-python</code> Meaning <code>&gt;=3.7</code> Python 3.7 and above <code>&gt;=3.7,&lt;3.11</code> Python 3.7, 3.8, 3.9 and 3.10 <code>&gt;=3.6,!=3.8.*,!=3.9.*</code> Python 3.6 and above, except 3.8 and 3.9"},{"location":"usage/project/#working-with-older-python-versions","title":"Working with older Python versions","text":"<p>Although PDM run on Python 3.8 and above, you can still have lower Python versions for your working project. But remember, if your project is a library, which needs to be built, published or installed, you make sure the PEP 517 build backend being used supports the lowest Python version you need. For instance, the default backend <code>pdm-backend</code> only works on Python 3.7+, so if you run <code>pdm build</code> on a project with Python 3.6, you will get an error. Most modern build backends have dropped the support for Python 3.6 and lower, so it is highly recommended to upgrade the Python version to 3.7+. Here are the supported Python range for some commonly used build backends, we only list those that support PEP 621 since otherwise PDM can't work with them.</p> Backend Supported Python Support PEP 621 <code>pdm-backend</code> <code>&gt;=3.7</code> Yes <code>setuptools&gt;=60</code> <code>&gt;=3.7</code> Experimental <code>hatchling</code> <code>&gt;=3.7</code> Yes <code>flit-core&gt;=3.4</code> <code>&gt;=3.6</code> Yes <code>flit-core&gt;=3.2,&lt;3.4</code> <code>&gt;=3.4</code> Yes <p>Note that if your project is an application (i.e. without the <code>name</code> metadata), the above limitation of backends does not apply. Therefore, if you don't need a build backend you can use any Python version <code>&gt;=2.7</code>.</p>"},{"location":"usage/project/#import-the-project-from-other-package-managers","title":"Import the project from other package managers","text":"<p>If you are already using other package manager tools like Pipenv or Poetry, it is easy to migrate to PDM. PDM provides <code>import</code> command so that you don't have to initialize the project manually, it now supports:</p> <ol> <li>Pipenv's <code>Pipfile</code></li> <li>Poetry's section in <code>pyproject.toml</code></li> <li>Flit's section in <code>pyproject.toml</code></li> <li><code>requirements.txt</code> format used by pip</li> <li>setuptools <code>setup.py</code>(It requires <code>setuptools</code> to be installed in the project environment. You can do this by configuring <code>venv.with_pip</code> to <code>true</code> for venv and <code>pdm add setuptools</code> for <code>__pypackages__</code>)</li> </ol> <p>Also, when you are executing <code>pdm init</code> or <code>pdm install</code>, PDM can auto-detect possible files to import if your PDM project has not been initialized yet.</p> <p>Info</p> <p>Converting a <code>setup.py</code> will execute the file with the project interpreter. Make sure <code>setuptools</code> is installed with the interpreter and the <code>setup.py</code> is trusted.</p>"},{"location":"usage/project/#working-with-version-control","title":"Working with version control","text":"<p>You must commit the <code>pyproject.toml</code> file. You should commit the <code>pdm.lock</code> and <code>pdm.toml</code> file. Do not commit the <code>.pdm-python</code> file.</p> <p>The <code>pyproject.toml</code> file must be committed as it contains the project's build metadata and dependencies needed for PDM. It is also commonly used by other python tools for configuration. Read more about the <code>pyproject.toml</code> file at Pip documentation.</p> <p>You should be committing the <code>pdm.lock</code> file, by doing so you ensure that all installers are using the same versions of dependencies. To learn how to update dependencies see update existing dependencies.</p> <p><code>pdm.toml</code> contains some project-wide configuration and it may be useful to commit it for sharing.</p> <p><code>.pdm-python</code> stores the Python path used by the current project and doesn't need to be shared.</p>"},{"location":"usage/project/#show-the-current-python-environment","title":"Show the current Python environment","text":"<pre><code>$ pdm info\nPDM version:\n  2.0.0\nPython Interpreter:\n  /opt/homebrew/opt/python@3.9/bin/python3.9 (3.9)\nProject Root:\n  /Users/fming/wkspace/github/test-pdm\nProject Packages:\n  /Users/fming/wkspace/github/test-pdm/__pypackages__/3.9\n\n# Show environment info\n$ pdm info --env\n{\n\"implementation_name\": \"cpython\",\n  \"implementation_version\": \"3.8.0\",\n  \"os_name\": \"nt\",\n  \"platform_machine\": \"AMD64\",\n  \"platform_release\": \"10\",\n  \"platform_system\": \"Windows\",\n  \"platform_version\": \"10.0.18362\",\n  \"python_full_version\": \"3.8.0\",\n  \"platform_python_implementation\": \"CPython\",\n  \"python_version\": \"3.8\",\n  \"sys_platform\": \"win32\"\n}\n</code></pre> <p>This command is useful for checking which mode is being used by the project:</p> <ul> <li>If Project Packages is <code>None</code>, virtualenv mode is enabled.</li> <li>Otherwise, PEP 582 mode is enabled.</li> </ul> <p>Now, you have set up a new PDM project and get a <code>pyproject.toml</code> file. Refer to metadata section about how to write <code>pyproject.toml</code> properly.</p>"},{"location":"usage/publish/","title":"Build and Publish","text":"<p>If you are developing a library, after adding dependencies to your project, and finishing the coding, it's time to build and publish your package. It is as simple as one command:</p> <pre><code>pdm publish\n</code></pre> <p>This will automatically build a wheel and a source distribution(sdist), and upload them to the PyPI index.</p> <p>To specify another repository other than PyPI, use the <code>--repository</code> option, the parameter can be either the upload URL or the name of the repository stored in the config file.</p> <pre><code>pdm publish --repository testpypi\npdm publish --repository https://test.pypi.org/legacy/\n</code></pre>"},{"location":"usage/publish/#publish-with-trusted-publishers","title":"Publish with trusted publishers","text":"<p>You can configure trusted publishers for PyPI so that you don't need to expose the PyPI tokens in the release workflow. To do this, follow the guide to add a publisher and write the GitHub Actions workflow as below:</p> <pre><code>jobs:\npypi-publish:\nname: upload release to PyPI\nruns-on: ubuntu-latest\npermissions:\n# This permission is needed for private repositories.\ncontents: read\n# IMPORTANT: this permission is mandatory for trusted publishing\nid-token: write\nsteps:\n- uses: actions/checkout@v3\n\n- uses: pdm-project/setup-pdm@v3\n\n- name: Publish package distributions to PyPI\nrun: pdm publish\n</code></pre>"},{"location":"usage/publish/#build-and-publish-separately","title":"Build and publish separately","text":"<p>You can also build the package and upload it in two steps, to allow you to inspect the built artifacts before uploading.</p> <pre><code>pdm build\n</code></pre> <p>There are many options to control the build process, depending on the backend used. Refer to the build configuration section for more details.</p> <p>The artifacts will be created at <code>dist/</code> and able to upload to PyPI.</p> <pre><code>pdm publish --no-build\n</code></pre>"},{"location":"usage/scripts/","title":"PDM Scripts","text":"<p>Like <code>npm run</code>, with PDM, you can run arbitrary scripts or commands with local packages loaded.</p>"},{"location":"usage/scripts/#arbitrary-scripts","title":"Arbitrary Scripts","text":"<pre><code>pdm run flask run -p 54321\n</code></pre> <p>It will run <code>flask run -p 54321</code> in the environment that is aware of packages in your project environment.</p>"},{"location":"usage/scripts/#user-scripts","title":"User Scripts","text":"<p>PDM also supports custom script shortcuts in the optional <code>[tool.pdm.scripts]</code> section of <code>pyproject.toml</code>.</p> <p>Note</p> <p>The <code>[tool.pdm.scripts]</code> directory must not be confused with <code>[project.scripts]</code>. The latter is used to install a command as part of your package, as explained here.</p> <p>You can then run <code>pdm run &lt;script_name&gt;</code> to invoke the script in the context of your PDM project. For example:</p> <pre><code>[tool.pdm.scripts]\nstart = \"flask run -p 54321\"\n</code></pre> <p>And then in your terminal:</p> <pre><code>$ pdm run start\nFlask server started at http://127.0.0.1:54321\n</code></pre> <p>Any following arguments will be appended to the command:</p> <pre><code>$ pdm run start -h 0.0.0.0\nFlask server started at http://0.0.0.0:54321\n</code></pre> <p>Yarn-like script shortcuts</p> <p>There is a builtin shortcut making all scripts available as root commands as long as the script does not conflict with any builtin or plugin-contributed command. Said otherwise, if you have a <code>start</code> script, you can run both <code>pdm run start</code> and <code>pdm start</code>. But if you have an <code>install</code> script, only <code>pdm run install</code> will run it, <code>pdm install</code> will still run the builtin <code>install</code> command.</p> <p>PDM supports 4 types of scripts:</p>"},{"location":"usage/scripts/#cmd","title":"<code>cmd</code>","text":"<p>Plain text scripts are regarded as normal command, or you can explicitly specify it:</p> <pre><code>[tool.pdm.scripts]\nstart = {cmd = \"flask run -p 54321\"}\n</code></pre> <p>In some cases, such as when wanting to add comments between parameters, it might be more convenient to specify the command as an array instead of a string:</p> <pre><code>[tool.pdm.scripts]\nstart = {cmd = [\n\"flask\",\n\"run\",\n# Important comment here about always using port 54321\n\"-p\", \"54321\"\n]}\n</code></pre>"},{"location":"usage/scripts/#shell","title":"<code>shell</code>","text":"<p>Shell scripts can be used to run more shell-specific tasks, such as pipeline and output redirecting. This is basically run via <code>subprocess.Popen()</code> with <code>shell=True</code>:</p> <pre><code>[tool.pdm.scripts]\nfilter_error = {shell = \"cat error.log|grep CRITICAL &gt; critical.log\"}\n</code></pre>"},{"location":"usage/scripts/#call","title":"<code>call</code>","text":"<p>The script can be also defined as calling a python function in the form <code>&lt;module_name&gt;:&lt;func_name&gt;</code>:</p> <pre><code>[tool.pdm.scripts]\nfoobar = {call = \"foo_package.bar_module:main\"}\n</code></pre> <p>The function can be supplied with literal arguments:</p> <pre><code>[tool.pdm.scripts]\nfoobar = {call = \"foo_package.bar_module:main('dev')\"}\n</code></pre>"},{"location":"usage/scripts/#composite","title":"<code>composite</code>","text":"<p>This script kind execute other defined scripts:</p> <pre><code>[tool.pdm.scripts]\nlint = \"flake8\"\ntest = \"pytest\"\nall = {composite = [\"lint\", \"test\"]}\n</code></pre> <p>Running <code>pdm run all</code> will run <code>lint</code> first and then <code>test</code> if <code>lint</code> succeeded.</p> <p>Added in version 2.13.0</p> <p>To override the default behavior and continue the execution of the remaining scripts after a failure, set the <code>keep_going</code> option to <code>true</code>:</p> <pre><code>[tool.pdm.scripts]\nlint = \"flake8\"\ntest = \"pytest\"\nall = {composite = [\"lint\", \"test\"]}\nall.keep_going = true\n</code></pre> <p>If <code>keep_going</code> set to <code>true</code> return code of composite script is either '0' if all succeeded or the code of last failed individual script.</p> <p>You can also provide arguments to the called scripts:</p> <pre><code>[tool.pdm.scripts]\nlint = \"flake8\"\ntest = \"pytest\"\nall = {composite = [\"lint mypackage/\", \"test -v tests/\"]}\n</code></pre> <p>Note</p> <p>Argument passed on the command line are given to each called task.</p>"},{"location":"usage/scripts/#script-options","title":"Script Options","text":""},{"location":"usage/scripts/#env","title":"<code>env</code>","text":"<p>All environment variables set in the current shell can be seen by <code>pdm run</code> and will be expanded when executed. Besides, you can also define some fixed environment variables in your <code>pyproject.toml</code>:</p> <pre><code>[tool.pdm.scripts]\nstart.cmd = \"flask run -p 54321\"\nstart.env = {FOO = \"bar\", FLASK_ENV = \"development\"}\n</code></pre> <p>Note how we use TOML's syntax to define a composite dictionary.</p> <p>About environment variable substitution</p> <p>Variables in script specifications can be substituted in all script types. In <code>cmd</code> scripts, only <code>${VAR}</code> syntax is supported on all platforms, however in <code>shell</code> scripts, the syntax is platform-dependent. For example, Windows cmd uses <code>%VAR%</code> while bash uses <code>$VAR</code>.</p> <p>Note</p> <p>Environment variables specified on a composite task level will override those defined by called tasks.</p>"},{"location":"usage/scripts/#env_file","title":"<code>env_file</code>","text":"<p>You can also store all environment variables in a dotenv file and let PDM read it:</p> <pre><code>[tool.pdm.scripts]\nstart.cmd = \"flask run -p 54321\"\nstart.env_file = \".env\"\n</code></pre> <p>The variables within the dotenv file will not override any existing environment variables. If you want the dotenv file to override existing environment variables use the following:</p> <pre><code>[tool.pdm.scripts]\nstart.cmd = \"flask run -p 54321\"\nstart.env_file.override = \".env\"\n</code></pre> <p>Note</p> <p>A dotenv file specified on a composite task level will override those defined by called tasks.</p>"},{"location":"usage/scripts/#working_dir","title":"<code>working_dir</code>","text":"<p>Added in version 2.13.0</p> <p>You can set the current working directory for the script:</p> <pre><code>[tool.pdm.scripts]\nstart.cmd = \"flask run -p 54321\"\nstart.working_dir = \"subdir\"\n</code></pre> <p>Relative paths are resolved against the project root.</p>"},{"location":"usage/scripts/#site_packages","title":"<code>site_packages</code>","text":"<p>To make sure the running environment is properly isolated from the outer Python interpreter, site-packages from the selected interpreter WON'T be loaded into <code>sys.path</code>, unless any of the following conditions holds:</p> <ol> <li>The executable is from <code>PATH</code> but not inside the <code>__pypackages__</code> folder.</li> <li><code>-s/--site-packages</code> flag is following <code>pdm run</code>.</li> <li><code>site_packages = true</code> is in either the script table or the global setting key <code>_</code>.</li> </ol> <p>Note that site-packages will always be loaded if running with PEP 582 enabled(without the <code>pdm run</code> prefix).</p>"},{"location":"usage/scripts/#shared-options","title":"Shared Options","text":"<p>If you want the options to be shared by all tasks run by <code>pdm run</code>, you can write them under a special key <code>_</code> in <code>[tool.pdm.scripts]</code> table:</p> <pre><code>[tool.pdm.scripts]\n_.env_file = \".env\"\nstart = \"flask run -p 54321\"\nmigrate_db = \"flask db upgrade\"\n</code></pre> <p>Besides, inside the tasks, <code>PDM_PROJECT_ROOT</code> environment variable will be set to the project root.</p>"},{"location":"usage/scripts/#arguments-placeholder","title":"Arguments placeholder","text":"<p>By default, all user provided extra arguments are simply appended to the command (or to all the commands for <code>composite</code> tasks).</p> <p>If you want more control over the user provided extra arguments, you can use the <code>{args}</code> placeholder. It is available for all script types and will be interpolated properly for each:</p> <pre><code>[tool.pdm.scripts]\ncmd = \"echo '--before {args} --after'\"\nshell = {shell = \"echo '--before {args} --after'\"}\ncomposite = {composite = [\"cmd --something\", \"shell {args}\"]}\n</code></pre> <p>will produce the following interpolations (those are not real scripts, just here to illustrate the interpolation):</p> <pre><code>$ pdm run cmd --user --provided\n--before --user --provided --after\n$ pdm run cmd\n--before --after\n$ pdm run shell --user --provided\n--before --user --provided --after\n$ pdm run shell\n--before --after\n$ pdm run composite --user --provided\ncmd --something\nshell --before --user --provided --after\n$ pdm run composite\ncmd --something\nshell --before --after\n</code></pre> <p>You may optionally provide default values that will be used if no user arguments are provided:</p> <pre><code>[tool.pdm.scripts]\ntest = \"echo '--before {args:--default --value} --after'\"\n</code></pre> <p>will produce the following:</p> <pre><code>$ pdm run test --user --provided\n--before --user --provided --after\n$ pdm run test\n--before --default --value --after\n</code></pre> <p>Note</p> <p>As soon a placeholder is detected, arguments are not appended anymore. This is important for <code>composite</code> scripts because if a placeholder is detected on one of the subtasks, none for the subtasks will have the arguments appended, you need to explicitly pass the placeholder to every nested command requiring it.</p> <p>Note</p> <p><code>call</code> scripts don't support the <code>{args}</code> placeholder as they have access to <code>sys.argv</code> directly to handle such complexe cases and more.</p>"},{"location":"usage/scripts/#pdm-placeholder","title":"<code>{pdm}</code> placeholder","text":"<p>Sometimes you may have multiple PDM installations, or <code>pdm</code> installed with a different name. This could for example occur in a CI/CD situation, or when working with different PDM versions in different repos. To make your scripts more robust you can use <code>{pdm}</code> to use the PDM entrypoint executing the script. This will expand to <code>{sys.executable} -m pdm</code>.</p> <p><pre><code>[tool.pdm.scripts]\nwhoami = { shell = \"echo `{pdm} -V` was called as '{pdm} -V'\" }\n</code></pre> will produce the following output: <pre><code>$ pdm whoami\nPDM, version 0.1.dev2501+g73651b7.d20231115 was called as /usr/bin/python3 -m pdm -V\n\n$ pdm2.8 whoami\nPDM, version 2.8.0 was called as &lt;snip&gt;/venvs/pdm2-8/bin/python -m pdm -V\n</code></pre></p> <p>Note</p> <p>While the above example uses PDM 2.8, this functionality was introduced in the 2.10 series and only backported for the showcase.</p>"},{"location":"usage/scripts/#show-the-list-of-scripts","title":"Show the List of Scripts","text":"<p>Use <code>pdm run --list/-l</code> to show the list of available script shortcuts:</p> <pre><code>$ pdm run --list\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Name        \u2502 Type  \u2502 Description               \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 test_cmd    \u2502 cmd   \u2502 flask db upgrade          \u2502\n\u2502 test_script \u2502 call  \u2502 call a python function    \u2502\n\u2502 test_shell  \u2502 shell \u2502 shell command             \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n</code></pre> <p>You can add an <code>help</code> option with the description of the script, and it will be displayed in the <code>Description</code> column in the above output.</p> <p>Note</p> <p>Tasks with a name starting with an underscore (<code>_</code>) are considered internal (helpers...) and are not shown in the listing.</p>"},{"location":"usage/scripts/#pre-post-scripts","title":"Pre &amp; Post Scripts","text":"<p>Like <code>npm</code>, PDM also supports tasks composition by pre and post scripts, pre script will be run before the given task and post script will be run after.</p> <pre><code>[tool.pdm.scripts]\npre_compress = \"{{ Run BEFORE the `compress` script }}\"\ncompress = \"tar czvf compressed.tar.gz data/\"\npost_compress = \"{{ Run AFTER the `compress` script }}\"\n</code></pre> <p>In this example, <code>pdm run compress</code> will run all these 3 scripts sequentially.</p> <p>The pipeline fails fast</p> <p>In a pipeline of pre - self - post scripts, a failure will cancel the subsequent execution.</p>"},{"location":"usage/scripts/#hook-scripts","title":"Hook Scripts","text":"<p>Under certain situations PDM will look for some special hook scripts for execution:</p> <ul> <li><code>post_init</code>: Run after <code>pdm init</code></li> <li><code>pre_install</code>: Run before installing packages</li> <li><code>post_install</code>: Run after packages are installed</li> <li><code>pre_lock</code>: Run before dependency resolution</li> <li><code>post_lock</code>: Run after dependency resolution</li> <li><code>pre_build</code>: Run before building distributions</li> <li><code>post_build</code>: Run after distributions are built</li> <li><code>pre_publish</code>: Run before publishing distributions</li> <li><code>post_publish</code>: Run after distributions are published</li> <li><code>pre_script</code>: Run before any script</li> <li><code>post_script</code>: Run after any script</li> <li><code>pre_run</code>: Run once before run script invocation</li> <li><code>post_run</code>: Run once after run script invocation</li> </ul> <p>Note</p> <p>Pre &amp; post scripts can't receive any arguments.</p> <p>Avoid name conflicts</p> <p>If there exists an <code>install</code> scripts under <code>[tool.pdm.scripts]</code> table, <code>pre_install</code> scripts can be triggered by both <code>pdm install</code> and <code>pdm run install</code>. So it is recommended to not use the preserved names.</p> <p>Note</p> <p>Composite tasks can also have pre and post scripts. Called tasks will run their own pre and post scripts.</p>"},{"location":"usage/scripts/#skipping-scripts","title":"Skipping scripts","text":"<p>Because, sometimes it is desirable to run a script but without its hooks or pre and post scripts, there is a <code>--skip=:all</code> which will disable all hooks, pre and post. There is also <code>--skip=:pre</code> and <code>--skip=:post</code> allowing to respectively skip all <code>pre_*</code> hooks and all <code>post_*</code> hooks.</p> <p>It is also possible to need a pre script but not the post one, or to need all tasks from a composite tasks except one. For those use cases, there is a finer grained <code>--skip</code> parameter accepting a list of tasks or hooks name to exclude.</p> <pre><code>pdm run --skip pre_task1,task2 my-composite\n</code></pre> <p>This command will run the <code>my-composite</code> task and skip the <code>pre_task1</code> hook as well as the <code>task2</code> and its hooks.</p> <p>You can also provide you skip list in <code>PDM_SKIP_HOOKS</code> environment variable but it will be overridden as soon as the <code>--skip</code> parameter is provided.</p> <p>There is more details on hooks and pre/post scripts behavior on the dedicated hooks page.</p>"},{"location":"usage/template/","title":"Create Project From a Template","text":"<p>Similar to <code>yarn create</code> and <code>npm create</code>, PDM also supports initializing or creating a project from a template. The template is given as a positional argument of <code>pdm init</code>, in one of the following forms:</p> <ul> <li><code>pdm init django</code> - Initialize the project from the template <code>https://github.com/pdm-project/template-django</code></li> <li><code>pdm init https://github.com/frostming/pdm-template-django</code> - Initialize the project from a Git URL. Both HTTPS and SSH URL are acceptable.</li> <li><code>pdm init django@v2</code> - To check out the specific branch or tag. Full Git URL also supports it.</li> <li><code>pdm init /path/to/template</code> - Initialize the project from a template directory on local filesystem.</li> <li><code>pdm init minimal</code> - Initialize with the builtin \"minimal\" template, that only generates a <code>pyproject.toml</code>.</li> </ul> <p>And <code>pdm init</code> will use the default template built in.</p> <p>The project will be initialized at the current directory, existing files with the same name will be overwritten. You can also use the <code>-p &lt;path&gt;</code> option to create a project at a new path.</p>"},{"location":"usage/template/#contribute-a-template","title":"Contribute a template","text":"<p>According to the first form of the template argument, <code>pdm init &lt;name&gt;</code> will refer to the template repository located at <code>https://github.com/pdm-project/template-&lt;name&gt;</code>. To contribute a template, you can create a template repository and establish a request to transfer the ownership to <code>pdm-project</code> organization(it can be found at the bottom of the repository settings page). The administrators of the organization will review the request and complete the subsequent steps. You will be added as the repository maintainer if the transfer is accepted.</p>"},{"location":"usage/template/#requirements-for-a-template","title":"Requirements for a template","text":"<p>A template repository must be a pyproject-based project, which contains a <code>pyproject.toml</code> file with PEP-621 compliant metadata. No other special config files are required.</p>"},{"location":"usage/template/#project-name-replacement","title":"Project name replacement","text":"<p>On initialization, the project name in the template will be replaced by the name of the new project. This is done by a recursive full-text search and replace. The import name, which is derived from the project name by replacing all non-alphanumeric characters with underscores and lowercasing, will also be replaced in the same way.</p> <p>For example, if the project name is <code>foo-project</code> in the template and you want to initialize a new project named <code>bar-project</code>, the following replacements will be made:</p> <ul> <li><code>foo-project</code> -&gt; <code>bar-project</code> in all <code>.md</code> files and <code>.rst</code> files</li> <li><code>foo_project</code> -&gt; <code>bar_project</code> in all <code>.py</code> files</li> <li><code>foo_project</code> -&gt; <code>bar_project</code> in the directory name</li> <li><code>foo_project.py</code> -&gt; <code>bar_project.py</code> in the file name</li> </ul> <p>Therefore, we don't support name replacement if the import name isn't derived from the project name.</p>"},{"location":"usage/template/#use-other-project-generators","title":"Use other project generators","text":"<p>If you are seeking for a more powerful project generator, you can use cookiecutter via <code>--cookiecutter</code> option and copier via <code>--copier</code> option.</p> <p>You need to install <code>cookiecutter</code> and <code>copier</code> respectively to use them. You can do this by running <code>pdm self add &lt;package&gt;</code>. To use them:</p> <pre><code>pdm init --cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python\n# or\npdm init --copier gh:pawamoy/copier-pdm --UNSAFE\n</code></pre>"},{"location":"usage/venv/","title":"Working with Virtual Environments","text":"<p>When you run <code>pdm init</code> command, PDM will ask for the Python interpreter to use in the project, which is the base interpreter to install dependencies and run tasks.</p> <p>Compared to PEP 582, virtual environments are considered more mature and have better support in the Python ecosystem as well as IDEs. Therefore, virtualenv is the default mode if not configured otherwise.</p> <p>Virtual environments will be used if the project interpreter (the interpreter stored in <code>.pdm-python</code>, which can be checked by <code>pdm info</code>) is from a virtualenv.</p>"},{"location":"usage/venv/#virtualenv-auto-creation","title":"Virtualenv auto-creation","text":"<p>By default, PDM prefers to use the virtualenv layout as other package managers do. When you run <code>pdm install</code> the first time on a new PDM-managed project, whose Python interpreter is not decided yet, PDM will create a virtualenv in <code>&lt;project_root&gt;/.venv</code>, and install dependencies into it. In the interactive session of <code>pdm init</code>, PDM will also ask to create a virtualenv for you.</p> <p>You can choose the backend used by PDM to create a virtualenv. Currently it supports three backends:</p> <ul> <li><code>virtualenv</code>(default)</li> <li><code>venv</code></li> <li><code>conda</code></li> </ul> <p>You can change it by <code>pdm config venv.backend [virtualenv|venv|conda]</code>.</p>"},{"location":"usage/venv/#create-a-virtualenv-yourself","title":"Create a virtualenv yourself","text":"<p>You can create more than one virtualenvs with whatever Python version you want.</p> <pre><code># Create a virtualenv based on 3.8 interpreter\n$ pdm venv create 3.8\n# Assign a different name other than the version string\n$ pdm venv create --name for-test 3.8\n# Use venv as the backend to create, support 3 backends: virtualenv(default), venv, conda\n$ pdm venv create --with venv 3.9\n</code></pre>"},{"location":"usage/venv/#the-location-of-virtualenvs","title":"The location of virtualenvs","text":"<p>If no <code>--name</code> is given, PDM will create the venv in <code>&lt;project_root&gt;/.venv</code>. Otherwise, virtualenvs go to the location specified by the <code>venv.location</code> configuration. They are named as <code>&lt;project_name&gt;-&lt;path_hash&gt;-&lt;name_or_python_version&gt;</code> to avoid name collision. You can disable the in-project virtualenv creation by <code>pdm config venv.in_project false</code>. And all virtualenvs will be created under <code>venv.location</code>.</p>"},{"location":"usage/venv/#reuse-the-virtualenv-you-created-elsewhere","title":"Reuse the virtualenv you created elsewhere","text":"<p>You can tell PDM to use a virtualenv you created in preceding steps, with <code>pdm use</code>:</p> <pre><code>pdm use -f /path/to/venv\n</code></pre>"},{"location":"usage/venv/#virtualenv-auto-detection","title":"Virtualenv auto-detection","text":"<p>When no interpreter is stored in the project config or <code>PDM_IGNORE_SAVED_PYTHON</code> env var is set, PDM will try to detect possible virtualenvs to use:</p> <ul> <li><code>venv</code>, <code>env</code>, <code>.venv</code> directories in the project root</li> <li>The currently activated virtualenv, unless <code>PDM_IGNORE_ACTIVE_VENV</code> is set</li> </ul>"},{"location":"usage/venv/#list-all-virtualenvs-created-with-this-project","title":"List all virtualenvs created with this project","text":"<pre><code>$ pdm venv list\nVirtualenvs created with this project:\n\n-  3.8.6: C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-3.8.6\n-  for-test: C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-for-test\n-  3.9.1: C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-3.9.1\n</code></pre>"},{"location":"usage/venv/#show-the-path-or-python-interpreter-of-a-virtualenv","title":"Show the path or python interpreter of a virtualenv","text":"<pre><code>$ pdm venv --path for-test\n$ pdm venv --python for-test\n</code></pre>"},{"location":"usage/venv/#remove-a-virtualenv","title":"Remove a virtualenv","text":"<pre><code>$ pdm venv remove for-test\nVirtualenvs created with this project:\nWill remove: C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-for-test, continue? [y/N]:y\nRemoved C:\\Users\\Frost Ming\\AppData\\Local\\pdm\\pdm\\venvs\\test-project-8Sgn_62n-for-test\n</code></pre>"},{"location":"usage/venv/#activate-a-virtualenv","title":"Activate a virtualenv","text":"<p>Instead of spawning a subshell like what <code>pipenv</code> and <code>poetry</code> do, <code>pdm venv</code> doesn't create the shell for you but print the activate command to the console. In this way you won't leave the current shell. You can then feed the output to <code>eval</code> to activate the virtualenv:</p> bash/csh/zshFishPowershell <pre><code>$ eval $(pdm venv activate for-test)\n(test-project-for-test) $  # Virtualenv entered\n</code></pre> <pre><code>$ eval (pdm venv activate for-test)\n</code></pre> <pre><code>PS1&gt; Invoke-Expression (pdm venv activate for-test)\n</code></pre> <p>Additionally, if the project interpreter is a venv Python, you can omit the name argument following activate.</p> <p>Note</p> <p><code>venv activate</code> does not switch the Python interpreter used by the project. It only changes the shell by injecting the virtualenv paths to environment variables. For the forementioned purpose, use the <code>pdm use</code> command.</p> <p>For more CLI usage, see the <code>pdm venv</code> documentation.</p> <p>Looking for <code>pdm shell</code>?</p> <p>PDM doesn't provide a <code>shell</code> command because many fancy shell functions may not work perfectly in a subshell, which brings a maintenance burden to support all the corner cases. However, you can still gain the ability via the following ways:</p> <ul> <li>Use <code>pdm run $SHELL</code>, this will spawn a subshell with the environment variables set properly. The subshell can be quit with <code>exit</code> or <code>Ctrl+D</code>.</li> <li>Add a shell function to activate the virtualenv, here is an example of BASH function that also works on ZSH:</li> </ul> <pre><code>pdm() {\nlocal command=$1\n\nif [[ \"$command\" == \"shell\" ]]; then\neval $(pdm venv activate)\nelse\ncommand pdm $@\nfi\n}\n</code></pre> <p>Copy and paste this function to your <code>~/.bashrc</code> file and restart your shell. </p> <p>For <code>fish</code> shell you can put the following into your <code>~/fish/config.fish</code> or in <code>~/.config/fish/config.fish</code></p> <pre><code>  function pdm\n      set cmd $argv[1]\n\n      if test \"$cmd\" = \"shell\"\n          eval (pdm venv activate)\n      else\n          command pdm $argv\n      end\n  end\n</code></pre> <p>Now you can run <code>pdm shell</code> to activate the virtualenv.   The virtualenv can be deactivated with <code>deactivate</code> command as usual.</p>"},{"location":"usage/venv/#prompt-customization","title":"Prompt customization","text":"<p>By default when you activate a virtualenv, the prompt will show: <code>{project_name}-{python_version}</code>.</p> <p>For example if your project is named <code>test-project</code>:</p> <pre><code>$ eval $(pdm venv activate for-test)\n(test-project-3.10) $  # {project_name} == test-project and {python_version} == 3.10\n</code></pre> <p>The format can be customized before virtualenv creation with the <code>venv.prompt</code> configuration or <code>PDM_VENV_PROMPT</code> environment variable (before a <code>pdm init</code> or <code>pdm venv create</code>). Available variables are:</p> <ul> <li><code>project_name</code>: name of your project</li> <li><code>python_version</code>: version of Python (used by the virtualenv)</li> </ul> <pre><code>$ PDM_VENV_PROMPT='{project_name}-py{python_version}' pdm venv create --name test-prompt\n$ eval $(pdm venv activate test-prompt)\n(test-project-py3.10) $\n</code></pre>"},{"location":"usage/venv/#run-a-command-in-a-virtual-environment-without-activating-it","title":"Run a command in a virtual environment without activating it","text":"<pre><code># Run a script\n$ pdm run --venv test test\n# Install packages\n$ pdm sync --venv test\n# List the packages installed\n$ pdm list --venv test\n</code></pre> <p>There are other commands supporting <code>--venv</code> flag or <code>PDM_IN_VENV</code> environment variable, see the CLI reference. You should create the virtualenv with <code>pdm venv create --name &lt;name&gt;</code> before using this feature.</p>"},{"location":"usage/venv/#switch-to-a-virtualenv-as-the-project-environment","title":"Switch to a virtualenv as the project environment","text":"<p>By default, if you use <code>pdm use</code> and select a non-venv Python, the project will be switched to PEP 582 mode. We also allow you to switch to a named virtual environment via the <code>--venv</code> flag:</p> <pre><code># Switch to a virtualenv named test\n$ pdm use --venv test\n# Switch to the in-project venv located at $PROJECT_ROOT/.venv\n$ pdm use --venv in-project\n</code></pre>"},{"location":"usage/venv/#disable-virtualenv-mode","title":"Disable virtualenv mode","text":"<p>You can disable the auto-creation and auto-detection for virtualenv by <code>pdm config python.use_venv false</code>. If venv is disabled, PEP 582 mode will always be used even if the selected interpreter is from a virtualenv.</p>"},{"location":"usage/venv/#including-pip-in-your-virtual-environment","title":"Including pip in your virtual environment","text":"<p>By default PDM will not include <code>pip</code> in virtual environments. This increases isolation by ensuring that only your dependencies are installed in the virtual environment.</p> <p>To install <code>pip</code> once (if for example you want to install arbitrary dependencies in CI) you can run:</p> <pre><code># Install pip in the virtual environment\n$ pdm run python -m ensurepip\n# Install arbitrary dependencies\n# These dependencies are not checked for conflicts against lockfile dependencies!\n$ pdm run python -m pip install coverage\n</code></pre> <p>Or you can create the virtual environment with <code>--with-pip</code>:</p> <pre><code>$ pdm venv create --with-pip 3.9\n</code></pre> <p>See the ensurepip docs for more details on <code>ensurepip</code>.</p> <p>If you want to permanently configure PDM to include <code>pip</code> in virtual environments you can use the <code>venv.with_pip</code> configuration.</p>"}]}
\ No newline at end of file
diff --git a/dev/sitemap.xml.gz b/dev/sitemap.xml.gz
index 3a0c4c8cca..0fc94939e3 100644
Binary files a/dev/sitemap.xml.gz and b/dev/sitemap.xml.gz differ
diff --git a/dev/usage/dependency/index.html b/dev/usage/dependency/index.html
index de30f65d57..36702e0d2e 100644
--- a/dev/usage/dependency/index.html
+++ b/dev/usage/dependency/index.html
@@ -591,6 +591,13 @@
     Inherit the metadata from parents
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#exclude-packages-newer-than-specific-date" class="md-nav__link">
+    Exclude packages newer than specific date
+  </a>
+  
 </li>
         
       </ul>
@@ -1210,6 +1217,13 @@
     Inherit the metadata from parents
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#exclude-packages-newer-than-specific-date" class="md-nav__link">
+    Exclude packages newer than specific date
+  </a>
+  
 </li>
         
       </ul>
@@ -1706,6 +1720,18 @@ <h3 id="inherit-the-metadata-from-parents">Inherit the metadata from parents<a c
 </div>
 <p>Previously, the <code>pdm lock</code> command would record package metadata as it is. When installing, PDM would start from the top requirements and traverse down to the leaf node of the dependency tree. It would then evaluate any marker it encounters against the current environment. If a marker is not satisfied, the package would be discarded. In other words, we need an additional "resolution" step in installation.</p>
 <p>When the <code>inherit_metadata</code> strategy is enabled, PDM will inherit and merge environment markers from a package's ancestors. These markers are then encoded in the lockfile during locking, resulting in faster installations. This has been enabled by default from version <code>2.11.0</code>, to disable this strategy in the config, use <code>pdm config strategy.inherit_metadata false</code>.</p>
+<h3 id="exclude-packages-newer-than-specific-date">Exclude packages newer than specific date<a class="headerlink" href="#exclude-packages-newer-than-specific-date" title="Permanent link">#</a></h3>
+<div class="admonition tip">
+<p class="admonition-title">Added in version 2.13.0</p>
+</div>
+<p>You can exclude packages that are newer than a specified date by passing the <code>--exclude-newer</code> option to <code>pdm lock</code>. This is useful when you want to lock the dependencies to a specific date, for example, to ensure reproducibility of the build.</p>
+<p>The date may be specified as a RFC 3339 timestamp (e.g., <code>2006-12-02T02:07:43Z</code>) or UTC date in the same format (e.g., <code>2006-12-02</code>).</p>
+<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><code>pdm<span class="w"> </span>lock<span class="w"> </span>--exclude-newer<span class="w"> </span><span class="m">2024</span>-01-01
+</code></pre></div></td></tr></table></div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The package index must support the <code>upload-time</code> field as specified in <a href="https://peps.python.org/pep-0700/">PEP 700</a>. If the field is not present for a given distribution, the distribution will be treated as unavailable.</p>
+</div>
 <h2 id="show-what-packages-are-installed">Show what packages are installed<a class="headerlink" href="#show-what-packages-are-installed" title="Permanent link">#</a></h2>
 <p>Similar to <code>pip list</code>, you can list all packages installed in the packages directory:</p>
 <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><code>pdm<span class="w"> </span>list