Basic usage

Basic usage#

For the basic usage introduction we will be installingpendulum, a datetime library.If you have not yet installed Poetry, refer to theIntroduction chapter.

Project setup#

First, let’s create our new project, let’s call itpoetry-demo:

poetry new poetry-demo

This will create thepoetry-demo directory with the following content:

poetry-demo├── pyproject.toml├── README.md├── src│   └── poetry_demo│       └── __init__.py└── tests    └── __init__.py

Thepyproject.toml file is what is the most important here. This will orchestrateyour project and its dependencies. For now, it looks like this:

[project]name="poetry-demo"version="0.1.0"description=""authors=[{name="Sébastien Eustace",email="sebastien@eustace.io"}]readme="README.md"requires-python=">=3.9"dependencies=[][build-system]requires=["poetry-core>=2.0.0,<3.0.0"]build-backend="poetry.core.masonry.api"

Poetry assumes your package contains a package with the same name asproject.name located in the root of yourproject. If this is not the case, populatetool.poetry.packages to specifyyour packages and their locations.

Similarly, the traditionalMANIFEST.in file is replaced by theproject.readme,tool.poetry.include, andtool.poetry.exclude sections.tool.poetry.exclude is additionally implicitly populated by your.gitignore. Forfull documentation on the project format, see thepyproject section of the documentation.

Setting a Python Version#

Poetry will require you to explicitly specify what versions of Python you intend to support, and its universal lockingwill guarantee that your project is installable (and all dependencies claim support for) all supported Python versions.Again, it’s important to remember that – unlike other dependencies – setting a Python version is merely specifying which versions of Python you intend to support.

For example, in thispyproject.toml file:

[project]requires-python=">=3.9"

we are allowing any version of Python 3 that is greater or equal than3.9.0.

When you runpoetry install, you must have access to some version of a Python interpreter that satisfies this constraint available on your system.Poetry will not install a Python interpreter for you.

Initialising a pre-existing project#

Instead of creating a new project, Poetry can be used to ‘initialize’ a pre-populateddirectory. To interactively create apyproject.toml file in directorypre-existing-project:

cd pre-existing-projectpoetry init

Operating modes#

Poetry can be operated in two different modes. The default mode is thepackage mode, which is the right modeif you want to package your project into an sdist or a wheel and perhaps publish it to a package index.In this mode, some metadata such asname andversion, which are required for packaging, are mandatory.Further, the project itself will be installed in editable mode when runningpoetry install.

If you want to use Poetry only for dependency management but not for packaging, you can use thenon-package mode:

[tool.poetry]package-mode=false

In this mode, metadata such asname andversion are optional.Therefore, it is not possible to build a distribution or publish the project to a package index.Further, when runningpoetry install, Poetry does not try to install the project itself,but only its dependencies (same aspoetry install --no-root).

Specifying dependencies#

If you want to add dependencies to your project, you can specify them in theproject section.

[project]# ...dependencies=["pendulum (>=2.1,<3.0)"]

As you can see, it takes a mapping ofpackage names andversion constraints.

Poetry uses this information to search for the right set of files in package “repositories” that you registerin thetool.poetry.source section, or onPyPI by default.

Also, instead of modifying thepyproject.toml file by hand, you can use theadd command.

$ poetry add pendulum

It will automatically find a suitable version constraintand install the package and sub-dependencies.

Poetry supports a richdependency specification syntax, including caret,tilde, wildcard, inequality andmultiple constraints requirements.

Using your virtual environment#

By default, Poetry creates a virtual environment in{cache-dir}/virtualenvs.You can change thecache-dir valueby editing the Poetry configuration.Additionally, you can use thevirtualenvs.in-project configuration variable to createvirtual environments within your project directory.

There are several ways to run commands within this virtual environment.

Usingpoetry run#

To run your script simply usepoetry run python your_script.py.Likewise if you have command line tools such aspytest orblack you can run them usingpoetry run pytest.

conda activate your_env_namewhich pythonpoetry run which pythonpoetry env activatewhich python

Activating the virtual environment#

SeeActivating the virtual environment.

Version constraints#

In our example, we are requesting thependulum package with the version constraint>=2.1.0 <3.0.0.This means any version greater or equal to 2.1.0 and less than 3.0.0.

Please readDependency specificationfor more in-depth information on versions, how versions relate to each other, and on the different ways you can specifydependencies.

Installing dependencies#

To install the defined dependencies for your project, just run theinstall command.

poetry install

When you run this command, one of two things may happen:

Installing withoutpoetry.lock#

If you have never run the command before and there is also nopoetry.lock file present,Poetry simply resolves all dependencies listed in yourpyproject.toml file and downloads the latest version of their files.

When Poetry has finished installing, it writes all the packages and their exact versions that it downloaded to thepoetry.lock file,locking the project to those specific versions.You should commit thepoetry.lock file to your project repo so that all people working on the project are locked to the same versions of dependencies (more below).

Installing withpoetry.lock#

This brings us to the second scenario. If there is already apoetry.lock file as well as apyproject.toml filewhen you runpoetry install, it means either you ran theinstall command before,or someone else on the project ran theinstall command and committed thepoetry.lock file to the project (which is good).

Either way, runninginstall when apoetry.lock file is present resolves and installs all dependencies that you listed inpyproject.toml,but Poetry uses the exact versions listed inpoetry.lock to ensure that the package versions are consistent for everyone working on your project.As a result you will have all dependencies requested by yourpyproject.toml file,but they may not all be at the very latest available versions(some dependencies listed in thepoetry.lock file may have released newer versions since the file was created).This is by design, it ensures that your project does not break because of unexpected changes in dependencies.

Committing yourpoetry.lock file to version control#

As an application developer#

Application developers commitpoetry.lock to get more reproducible builds.

Committing this file to VC is important because it will cause anyone who sets up the projectto use the exact same versions of the dependencies that you are using.Your CI server, production machines, other developers in your team,everything and everyone runs on the same dependencies,which mitigates the potential for bugs affecting only some parts of the deployments.Even if you develop alone, in six months when reinstalling the project you can feel confidentthe dependencies installed are still working even if your dependencies released many new versions since then.(See note below about using the update command.)

As a library developer#

Library developers have more to consider. Your users are application developers, and your library will run in a Python environment you don’t control.

The application ignores your library’s lock file. It can use whatever dependency version meets the constraints in yourpyproject.toml. The application will probably use the latest compatible dependency version. If your library’spoetry.lock falls behind some new dependency version that breaks things for your users, you’re likely to be the last to find out about it.

A simple way to avoid such a scenario is to omit thepoetry.lock file. However, by doing so, you sacrifice reproducibility and performance to a certain extent. Without a lockfile, it can be difficult to find the reason for failing tests, because in addition to obvious code changes an unnoticed library update might be the culprit. Further, Poetry will have to lock before installing a dependency ifpoetry.lock has been omitted. Depending on the number of dependencies, locking may take a significant amount of time.

If you do not want to give up the reproducibility and performance benefits, consider a regular refresh ofpoetry.lock to stay up-to-date and reduce the risk of sudden breakage for users.

Installing dependencies only#

The current project is installed ineditable mode by default.

If you want to install the dependencies only, run theinstall command with the--no-root flag:

poetry install --no-root

Updating dependencies to their latest versions#

As mentioned above, thepoetry.lock file prevents you from automatically getting the latest versionsof your dependencies.To update to the latest versions, use theupdate command.This will fetch the latest matching versions (according to yourpyproject.toml file)and update the lock file with the new versions.(This is equivalent to deleting thepoetry.lock file and runninginstall again.)