To start with, create a new project with
You will need to answer a few questions, to help PDM to create a
pyproject.toml file for you.
Choose a Python interpreter#
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
.pdm-python and used by subsequent commands. You can also change it later with
Alternatively, you can specify the Python interpreter path via
PDM_PYTHON environment variable. When it is set, the path saved in
.pdm-python will be ignored.
Virtualenv or not#
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.
If the selected Python interpreter is in a virtual environment, PDM will use it as the project environment and install dependencies
into it. Otherwise,
__pypackages__ will be created in the project root and dependencies will be installed into it.
For the difference between these two approaches, please refer to the corresponding sections in the docs:
Library or Application#
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.
In PDM, if you choose to create a library, PDM will add a
version field to the
pyproject.toml file, as well as a
[build-system] 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
pyproject.toml 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
pdm install or
pdm sync, unless
--no-self is specified.
You need to set an appropriate
requires-python value for your project. This is an important property that affects how dependencies are resolved. Basically, each package's
requires-python must cover the project's
requires-python range. For example, consider the following setup:
requires-python = ">=3.9"
requires-python = ">=3.7,<3.11"
Resolving the dependencies will cause a
Because the dependency's
>=3.7,<3.11, it doesn't cover the project's
requires-python range of
>=3.9. In other words, the project promises to work on Python 3.11 and above, but the dependency doesn't support it. Since PDM creates a cross-platform lockfile that should work on all Python versions within the
requires-python range, it can't find a valid resolution.
To fix this, you need add a maximum version to
The value of
requires-python is a version specifier as defined in PEP 440. Here are some examples:
||Python 3.7 and above|
||Python 3.7, 3.8 and 3.10|
||Python 3.6 and above, except 3.8 and 3.9|
Working with Python < 3.7#
Although PDM run on Python 3.7 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
pdm-pep517 only works on Python 3.7+, so if you run
pdm build 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.
|Backend||Supported Python||Support PEP 621|
Note that if your project is an application(without
name metadata), the above limitation of backends don't apply, since you don't need a build backend after all, and you can use a Python version up to
Import the project from other package managers#
If you are already using other package manager tools like Pipenv or Poetry, it is easy to migrate to PDM.
import command so that you don't have to initialize the project manually, it now supports:
- Poetry's section in
- Flit's section in
requirements.txtformat used by pip
setuptoolsto be installed in the project environment. You can do this by configuring
truefor venv and
pdm add setuptoolsfor
Also, when you are executing
pdm init or
pdm install, PDM can auto-detect possible files to import if your PDM project has not been initialized yet.
setup.py will execute the file with the project interpreter. Make sure
setuptools is installed with the interpreter and the
setup.py is trusted.
Working with version control#
You must commit the
pyproject.toml file. You should commit the
pdm.toml file. Do not commit the
pyproject.toml 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
pyproject.toml file at
You should be committing the
pdm.lock 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.
pdm.toml contains some project-wide configuration and it may be useful to commit it for sharing.
.pdm-python stores the Python path used by the current project and doesn't need to be shared.
Show the current Python environment#
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
This command is useful for checking which mode is being used by the project:
- If Project Packages is
None, virtualenv mode is enabled.
- Otherwise, PEP 582 mode is enabled.
Now, you have setup a new PDM project and get a
pyproject.toml file. Refer to metadata section
about how to write