🕷️ Crawler Inspector

[Home ](https://python-poetry.org/) 2\.3 - [main](https://python-poetry.org/docs/main/) - [2\.3](https://python-poetry.org/docs/) - [1\.8](https://python-poetry.org/docs/1.8/) Use dark mode Open menu - [Documentation](https://python-poetry.org/docs/) [Introduction Poetry is a tool for dependency management and packaging in Python.](https://python-poetry.org/docs/) [Basic usage For the basic usage introduction we will be installing pendulum, a datetime library.](https://python-poetry.org/docs/basic-usage/) [Managing dependencies Poetry supports specifying main dependencies in the project.dependencies section of your pyproject.toml according to PEP 621.](https://python-poetry.org/docs/managing-dependencies/) [Libraries This chapter will tell you how to make your library installable through Poetry. Versioning Poetry requires PEP 440-compliant versions for all projects. While Poetry does not enforce any release convention, it used to encourage the use of semantic versioning within the scope of PEP 440 and supports version constraints that are especially suitable for semver. Note As an example, 1.0.0-hotfix.1 is not compatible with PEP 440.](https://python-poetry.org/docs/libraries/) [Commands You’ve already learned how to use the command-line interface to do some things.](https://python-poetry.org/docs/cli/) [Configuration Poetry can be configured via the config command (see more about its usage here) or directly in the config.toml file that will be automatically created when you first run that command.](https://python-poetry.org/docs/configuration/) [Repositories Poetry supports the use of PyPI and private repositories for discovery of packages as well as for publishing your projects. By default, Poetry is configured to use the PyPI repository, for package installation and publishing. So, when you add dependencies to your project, Poetry will assume they are available on PyPI. This represents most cases and will likely be enough for most users. Private Repository Example Installing from private package sources By default, Poetry discovers and installs packages from PyPI.](https://python-poetry.org/docs/repositories/) [Managing environments Poetry makes project environment isolation one of its core features. What this means is that it will always work isolated from your global Python installation.](https://python-poetry.org/docs/managing-environments/) [Dependency specification Dependencies for a project can be specified in various forms, which depend on the type of the dependency and on the optional constraints that might be needed for it to be installed. project.dependencies and tool.poetry.dependencies Prior Poetry 2.0, dependencies had to be declared in the tool.poetry.dependencies section of the pyproject.toml file. \[tool.poetry.dependencies\] requests = "^2.13.0" With Poetry 2.0, you should consider using the project.dependencies section instead. \[project\] \# ...](https://python-poetry.org/docs/dependency-specification/) [Plugins Poetry supports using and building plugins if you wish to alter or expand Poetry’s functionality with your own. For example if your environment poses special requirements on the behaviour of Poetry which do not apply to the majority of its users or if you wish to accomplish something with Poetry in a way that is not desired by most users. In these cases you could consider creating a plugin to handle your specific logic. .](https://python-poetry.org/docs/plugins/) [The pyproject.toml file In package mode, the only required fields are name and version (either in the project section or in the tool.poetry section).](https://python-poetry.org/docs/pyproject/) [Contributing to Poetry First off, thanks for taking the time to contribute! The following is a set of guidelines for contributing to Poetry on GitHub.](https://python-poetry.org/docs/contributing/) [Community Badge For any projects using Poetry, you may add its official badge somewhere prominent like the README. Markdown \[!\[Poetry\](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)\](https://python-poetry.org/) reStructuredText ..](https://python-poetry.org/docs/community/) [FAQ Why is the dependency resolution process slow? While the dependency resolver at the heart of Poetry is highly optimized and should be fast enough for most cases, with certain sets of dependencies, it can take time to find a valid solution. This is due to the fact that not all libraries on PyPI have properly declared their metadata and, as such, they are not available via the PyPI JSON API.](https://python-poetry.org/docs/faq/) [pre-commit hooks pre-commit is a framework for building and running git hooks.](https://python-poetry.org/docs/pre-commit-hooks/) [Building extension modules Building Extension Modules Warning While this feature has been around since almost the beginning of the Poetry project and has needed minimal changes, it is still considered unstable.](https://python-poetry.org/docs/building-extension-modules/) [2\.3 Stable Documentation for the latest, **stable**, branch.](https://python-poetry.org/docs/) [main Development Documentation for the latest, **in-development**, branch.](https://python-poetry.org/docs/main/) - [Blog](https://python-poetry.org/blog/) - [History](https://python-poetry.org/history/)  Close menu [Documentation](https://python-poetry.org/docs/) [Blog](https://python-poetry.org/blog/) [History](https://python-poetry.org/history/) - [Introduction](https://python-poetry.org/docs/) - [Basic usage](https://python-poetry.org/docs/basic-usage/) - [Project setup](https://python-poetry.org/docs/basic-usage/#project-setup) - [Setting a Python Version](https://python-poetry.org/docs/basic-usage/#setting-a-python-version) - [Initialising a pre-existing project](https://python-poetry.org/docs/basic-usage/#initialising-a-pre-existing-project) - [Operating modes](https://python-poetry.org/docs/basic-usage/#operating-modes) - [Specifying dependencies](https://python-poetry.org/docs/basic-usage/#specifying-dependencies) - [Using your virtual environment](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment) - [Using `poetry run`](https://python-poetry.org/docs/basic-usage/#using-poetry-run) - [Activating the virtual environment](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment) - [Version constraints](https://python-poetry.org/docs/basic-usage/#version-constraints) - [Installing dependencies](https://python-poetry.org/docs/basic-usage/#installing-dependencies) - [Installing without `poetry.lock`](https://python-poetry.org/docs/basic-usage/#installing-without-poetrylock) - [Installing with `poetry.lock`](https://python-poetry.org/docs/basic-usage/#installing-with-poetrylock) - [Committing your `poetry.lock` file to version control](https://python-poetry.org/docs/basic-usage/#committing-your-poetrylock-file-to-version-control) - [Installing dependencies only](https://python-poetry.org/docs/basic-usage/#installing-dependencies-only) - [Updating dependencies to their latest versions](https://python-poetry.org/docs/basic-usage/#updating-dependencies-to-their-latest-versions) - [Managing dependencies](https://python-poetry.org/docs/managing-dependencies/) - [Libraries](https://python-poetry.org/docs/libraries/) - [Commands](https://python-poetry.org/docs/cli/) - [Configuration](https://python-poetry.org/docs/configuration/) - [Repositories](https://python-poetry.org/docs/repositories/) - [Managing environments](https://python-poetry.org/docs/managing-environments/) - [Dependency specification](https://python-poetry.org/docs/dependency-specification/) - [Plugins](https://python-poetry.org/docs/plugins/) - [The pyproject.toml file](https://python-poetry.org/docs/pyproject/) - [Contributing to Poetry](https://python-poetry.org/docs/contributing/) - [Community](https://python-poetry.org/docs/community/) - [FAQ](https://python-poetry.org/docs/faq/) - [pre-commit hooks](https://python-poetry.org/docs/pre-commit-hooks/) - [Building extension modules](https://python-poetry.org/docs/building-extension-modules/) Basic usage - [Introduction](https://python-poetry.org/docs/) - [Basic usage](https://python-poetry.org/docs/basic-usage/) - [Managing dependencies](https://python-poetry.org/docs/managing-dependencies/) - [Libraries](https://python-poetry.org/docs/libraries/) - [Commands](https://python-poetry.org/docs/cli/) - [Configuration](https://python-poetry.org/docs/configuration/) - [Repositories](https://python-poetry.org/docs/repositories/) - [Managing environments](https://python-poetry.org/docs/managing-environments/) - [Dependency specification](https://python-poetry.org/docs/dependency-specification/) - [Plugins](https://python-poetry.org/docs/plugins/) - [The pyproject.toml file](https://python-poetry.org/docs/pyproject/) - [Contributing to Poetry](https://python-poetry.org/docs/contributing/) - [Community](https://python-poetry.org/docs/community/) - [FAQ](https://python-poetry.org/docs/faq/) - [pre-commit hooks](https://python-poetry.org/docs/pre-commit-hooks/) - [Building extension modules](https://python-poetry.org/docs/building-extension-modules/) # Basic usage - [Project setup](https://python-poetry.org/docs/basic-usage/#project-setup) - [Setting a Python Version](https://python-poetry.org/docs/basic-usage/#setting-a-python-version) - [Initialising a pre-existing project](https://python-poetry.org/docs/basic-usage/#initialising-a-pre-existing-project) - [Operating modes](https://python-poetry.org/docs/basic-usage/#operating-modes) - [Specifying dependencies](https://python-poetry.org/docs/basic-usage/#specifying-dependencies) - [Using your virtual environment](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment) - [Using `poetry run`](https://python-poetry.org/docs/basic-usage/#using-poetry-run) - [Activating the virtual environment](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment) - [Version constraints](https://python-poetry.org/docs/basic-usage/#version-constraints) - [Installing dependencies](https://python-poetry.org/docs/basic-usage/#installing-dependencies) - [Installing without `poetry.lock`](https://python-poetry.org/docs/basic-usage/#installing-without-poetrylock) - [Installing with `poetry.lock`](https://python-poetry.org/docs/basic-usage/#installing-with-poetrylock) - [Committing your `poetry.lock` file to version control](https://python-poetry.org/docs/basic-usage/#committing-your-poetrylock-file-to-version-control) - [Installing dependencies only](https://python-poetry.org/docs/basic-usage/#installing-dependencies-only) - [Updating dependencies to their latest versions](https://python-poetry.org/docs/basic-usage/#updating-dependencies-to-their-latest-versions) # Basic usage [\#](https://python-poetry.org/docs/basic-usage/#basic-usage) For the basic usage introduction we will be installing `pendulum`, a datetime library. If you have not yet installed Poetry, refer to the [Introduction](https://python-poetry.org/docs/ "Introduction") chapter. ## Project setup [\#](https://python-poetry.org/docs/basic-usage/#project-setup) First, let’s create our new project, let’s call it `poetry-demo`: ``` poetry new poetry-demo ``` This will create the `poetry-demo` directory with the following content: ``` poetry-demo ├── pyproject.toml ├── README.md ├── src │ └── poetry_demo │ └── __init__.py └── tests └── __init__.py ``` The `pyproject.toml` file is what is the most important here. This will orchestrate your 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 as `project.name` located in the root of your project. If this is not the case, populate [`tool.poetry.packages`](https://python-poetry.org/docs/pyproject/#packages) to specify your packages and their locations. Similarly, the traditional `MANIFEST.in` file is replaced by the `project.readme`, `tool.poetry.include`, and `tool.poetry.exclude` sections. `tool.poetry.exclude` is additionally implicitly populated by your `.gitignore`. For full documentation on the project format, see the [pyproject section](https://python-poetry.org/docs/pyproject/) of the documentation. ### Setting a Python Version [\#](https://python-poetry.org/docs/basic-usage/#setting-a-python-version) Note Unlike with other packages, Poetry will not automatically install a python interpreter for you. If you want to run Python files in your package like a script or application, you must *bring your own* python interpreter to run them. Poetry will require you to explicitly specify what versions of Python you intend to support, and its universal locking will 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 this `pyproject.toml` file: ``` [project] requires-python = ">=3.9" ``` we are allowing any version of Python 3 that is greater or equal than `3.9.0`. When you run `poetry 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 [\#](https://python-poetry.org/docs/basic-usage/#initialising-a-pre-existing-project) Instead of creating a new project, Poetry can be used to ‘initialize’ a pre-populated directory. To interactively create a `pyproject.toml` file in directory `pre-existing-project`: ``` cd pre-existing-project poetry init ``` ### Operating modes [\#](https://python-poetry.org/docs/basic-usage/#operating-modes) Poetry can be operated in two different modes. The default mode is the **package mode**, which is the right mode if 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 as `name` and `version`, which are required for packaging, are mandatory. Further, the project itself will be installed in editable mode when running `poetry install`. If you want to use Poetry only for dependency management but not for packaging, you can use the **non-package mode**: ``` [tool.poetry] package-mode = false ``` In this mode, metadata such as `name` and `version` are optional. Therefore, it is not possible to build a distribution or publish the project to a package index. Further, when running `poetry install`, Poetry does not try to install the project itself, but only its dependencies (same as `poetry install --no-root`). Note In the [pyproject section](https://python-poetry.org/docs/pyproject/) you can see which fields are required in package mode. ### Specifying dependencies [\#](https://python-poetry.org/docs/basic-usage/#specifying-dependencies) If you want to add dependencies to your project, you can specify them in the `project` section. ``` [project] # ... dependencies = [ "pendulum (>=2.1,<3.0)" ] ``` As you can see, it takes a mapping of **package names** and **version constraints**. Poetry uses this information to search for the right set of files in package “repositories” that you register in the `tool.poetry.source` section, or on [PyPI](https://pypi.org/) by default. Also, instead of modifying the `pyproject.toml` file by hand, you can use the `add` command. ``` $ poetry add pendulum ``` It will automatically find a suitable version constraint **and install** the package and sub-dependencies. Poetry supports a rich [dependency specification](https://python-poetry.org/docs/dependency-specification/) syntax, including caret, tilde, wildcard, inequality and [multiple constraints](https://python-poetry.org/docs/dependency-specification/#multiple-constraints-dependencies) requirements. ## Using your virtual environment [\#](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment) By default, Poetry creates a virtual environment in `{cache-dir}/virtualenvs`. You can change the [`cache-dir`](https://python-poetry.org/docs/configuration/#cache-dir "cache-dir configuration documentation") value by editing the Poetry configuration. Additionally, you can use the [`virtualenvs.in-project`](https://python-poetry.org/docs/configuration/#virtualenvsin-project) configuration variable to create virtual environments within your project directory. There are several ways to run commands within this virtual environment. Note **External virtual environment management** Poetry will detect and respect an existing virtual environment that has been externally activated. This is a powerful mechanism that is intended to be an alternative to Poetry’s built-in, simplified environment management. To take advantage of this, simply activate a virtual environment using your preferred method or tooling, before running any Poetry commands that expect to manipulate an environment. ### Using `poetry run` [\#](https://python-poetry.org/docs/basic-usage/#using-poetry-run) To run your script simply use `poetry run python your_script.py`. Likewise if you have command line tools such as `pytest` or `black` you can run them using `poetry run pytest`. Note If managing your own virtual environment externally, you do not need to use `poetry run` since you will, presumably, already have activated that virtual environment and made available the correct python instance. For example, these commands should output the same python path: ``` conda activate your_env_name which python poetry run which python eval "$(poetry env activate)" which python ``` ### Activating the virtual environment [\#](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment) See [Activating the virtual environment](https://python-poetry.org/docs/managing-environments/#activating-the-environment). ## Version constraints [\#](https://python-poetry.org/docs/basic-usage/#version-constraints) In our example, we are requesting the `pendulum` 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 read [Dependency specification](https://python-poetry.org/docs/dependency-specification/ "Dependency specification documentation") for more in-depth information on versions, how versions relate to each other, and on the different ways you can specify dependencies. Note **How does Poetry download the right files?** When you specify a dependency in `pyproject.toml`, Poetry first takes the name of the package that you have requested and searches for it in any repository you have registered using the `repositories` key. If you have not registered any extra repositories, or it does not find a package with that name in the repositories you have specified, it falls back to PyPI. When Poetry finds the right package, it then attempts to find the best match for the version constraint you have specified. ## Installing dependencies [\#](https://python-poetry.org/docs/basic-usage/#installing-dependencies) To install the defined dependencies for your project, just run the [`install`](https://python-poetry.org/docs/cli/#install) command. ``` poetry install ``` When you run this command, one of two things may happen: ### Installing without `poetry.lock` [\#](https://python-poetry.org/docs/basic-usage/#installing-without-poetrylock) If you have never run the command before and there is also no `poetry.lock` file present, Poetry simply resolves all dependencies listed in your `pyproject.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 the `poetry.lock` file, locking the project to those specific versions. You should commit the `poetry.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 with `poetry.lock` [\#](https://python-poetry.org/docs/basic-usage/#installing-with-poetrylock) This brings us to the second scenario. If there is already a `poetry.lock` file as well as a `pyproject.toml` file when you run `poetry install`, it means either you ran the `install` command before, or someone else on the project ran the `install` command and committed the `poetry.lock` file to the project (which is good). Either way, running `install` when a `poetry.lock` file is present resolves and installs all dependencies that you listed in `pyproject.toml`, but Poetry uses the exact versions listed in `poetry.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 your `pyproject.toml` file, but they may not all be at the very latest available versions (some dependencies listed in the `poetry.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 your `poetry.lock` file to version control [\#](https://python-poetry.org/docs/basic-usage/#committing-your-poetrylock-file-to-version-control) #### As an application developer [\#](https://python-poetry.org/docs/basic-usage/#as-an-application-developer) Application developers commit `poetry.lock` to get more reproducible builds. Committing this file to VC is important because it will cause anyone who sets up the project to 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 confident the dependencies installed are still working even if your dependencies released many new versions since then. (See note below about using the update command.) Warning If you have added the recommended [`[build-system]`](https://python-poetry.org/docs/pyproject/#poetry-and-pep-517) section to your project’s pyproject.toml then you *can* successfully install your project and its dependencies into a virtual environment using a command like `pip install -e .`. However, pip will not use the lock file to determine dependency versions as the poetry-core build system is intended for library developers (see next section). #### As a library developer [\#](https://python-poetry.org/docs/basic-usage/#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 your `pyproject.toml`. The application will probably use the latest compatible dependency version. If your library’s `poetry.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 the `poetry.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 if `poetry.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 of `poetry.lock` to stay up-to-date and reduce the risk of sudden breakage for users. ### Installing dependencies only [\#](https://python-poetry.org/docs/basic-usage/#installing-dependencies-only) The current project is installed in [editable](https://pip.pypa.io/en/stable/topics/local-project-installs/) mode by default. If you want to install the dependencies only, run the `install` command with the `--no-root` flag: ``` poetry install --no-root ``` ## Updating dependencies to their latest versions [\#](https://python-poetry.org/docs/basic-usage/#updating-dependencies-to-their-latest-versions) As mentioned above, the `poetry.lock` file prevents you from automatically getting the latest versions of your dependencies. To update to the latest versions, use the `update` command. This will fetch the latest matching versions (according to your `pyproject.toml` file) and update the lock file with the new versions. (This is equivalent to deleting the `poetry.lock` file and running `install` again.) Note Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml` are not synchronized. ## Footer  Python packaging and dependency management made easy. [GitHub](https://github.com/python-poetry) [Discord](https://discord.com/invite/awxPgve) ### Documentation - [Introduction](https://python-poetry.org/docs/) - [Basic usage](https://python-poetry.org/docs/basic-usage/) - [Managing dependencies](https://python-poetry.org/docs/managing-dependencies/) - [Libraries](https://python-poetry.org/docs/libraries/) - [Commands](https://python-poetry.org/docs/cli/) - [Configuration](https://python-poetry.org/docs/configuration/) - [Repositories](https://python-poetry.org/docs/repositories/) - [Managing environments](https://python-poetry.org/docs/managing-environments/) - [Dependency specification](https://python-poetry.org/docs/dependency-specification/) - [Plugins](https://python-poetry.org/docs/plugins/) - [The pyproject.toml file](https://python-poetry.org/docs/pyproject/) - [Contributing to Poetry](https://python-poetry.org/docs/contributing/) - [Community](https://python-poetry.org/docs/community/) - [FAQ](https://python-poetry.org/docs/faq/) - [pre-commit hooks](https://python-poetry.org/docs/pre-commit-hooks/) - [Building extension modules](https://python-poetry.org/docs/building-extension-modules/) ### Github - [Project](https://github.com/python-poetry/poetry) - [Issues](https://github.com/python-poetry/poetry/issues) - [Discussions](https://github.com/python-poetry/poetry/discussions) ### Other Projects - [poetry-core](https://github.com/python-poetry/poetry-core) - [install.python-poetry.org](https://github.com/python-poetry/install.python-poetry.org) - [Bundle plugin](https://github.com/python-poetry/poetry-plugin-bundle) - [Export plugin](https://github.com/python-poetry/poetry-plugin-export) Copyright © 2018-2026. All Rights Reserved. Powered by

- [Project setup](https://python-poetry.org/docs/basic-usage/#project-setup) - [Setting a Python Version](https://python-poetry.org/docs/basic-usage/#setting-a-python-version) - [Initialising a pre-existing project](https://python-poetry.org/docs/basic-usage/#initialising-a-pre-existing-project) - [Operating modes](https://python-poetry.org/docs/basic-usage/#operating-modes) - [Specifying dependencies](https://python-poetry.org/docs/basic-usage/#specifying-dependencies) - [Using your virtual environment](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment) - [Using `poetry run`](https://python-poetry.org/docs/basic-usage/#using-poetry-run) - [Activating the virtual environment](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment) - [Version constraints](https://python-poetry.org/docs/basic-usage/#version-constraints) - [Installing dependencies](https://python-poetry.org/docs/basic-usage/#installing-dependencies) - [Installing without `poetry.lock`](https://python-poetry.org/docs/basic-usage/#installing-without-poetrylock) - [Installing with `poetry.lock`](https://python-poetry.org/docs/basic-usage/#installing-with-poetrylock) - [Committing your `poetry.lock` file to version control](https://python-poetry.org/docs/basic-usage/#committing-your-poetrylock-file-to-version-control) - [Installing dependencies only](https://python-poetry.org/docs/basic-usage/#installing-dependencies-only) - [Updating dependencies to their latest versions](https://python-poetry.org/docs/basic-usage/#updating-dependencies-to-their-latest-versions) ## Basic usage [\#](https://python-poetry.org/docs/basic-usage/#basic-usage) For the basic usage introduction we will be installing `pendulum`, a datetime library. If you have not yet installed Poetry, refer to the [Introduction](https://python-poetry.org/docs/ "Introduction") chapter. ## Project setup [\#](https://python-poetry.org/docs/basic-usage/#project-setup) First, let’s create our new project, let’s call it `poetry-demo`: ``` poetry new poetry-demo ``` This will create the `poetry-demo` directory with the following content: ``` poetry-demo ├── pyproject.toml ├── README.md ├── src │ └── poetry_demo │ └── __init__.py └── tests └── __init__.py ``` The `pyproject.toml` file is what is the most important here. This will orchestrate your 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 as `project.name` located in the root of your project. If this is not the case, populate [`tool.poetry.packages`](https://python-poetry.org/docs/pyproject/#packages) to specify your packages and their locations. Similarly, the traditional `MANIFEST.in` file is replaced by the `project.readme`, `tool.poetry.include`, and `tool.poetry.exclude` sections. `tool.poetry.exclude` is additionally implicitly populated by your `.gitignore`. For full documentation on the project format, see the [pyproject section](https://python-poetry.org/docs/pyproject/) of the documentation. ### Setting a Python Version [\#](https://python-poetry.org/docs/basic-usage/#setting-a-python-version) Note Unlike with other packages, Poetry will not automatically install a python interpreter for you. If you want to run Python files in your package like a script or application, you must *bring your own* python interpreter to run them. Poetry will require you to explicitly specify what versions of Python you intend to support, and its universal locking will 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 this `pyproject.toml` file: ``` [project] requires-python = ">=3.9" ``` we are allowing any version of Python 3 that is greater or equal than `3.9.0`. When you run `poetry 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 [\#](https://python-poetry.org/docs/basic-usage/#initialising-a-pre-existing-project) Instead of creating a new project, Poetry can be used to ‘initialize’ a pre-populated directory. To interactively create a `pyproject.toml` file in directory `pre-existing-project`: ``` cd pre-existing-project poetry init ``` ### Operating modes [\#](https://python-poetry.org/docs/basic-usage/#operating-modes) Poetry can be operated in two different modes. The default mode is the **package mode**, which is the right mode if 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 as `name` and `version`, which are required for packaging, are mandatory. Further, the project itself will be installed in editable mode when running `poetry install`. If you want to use Poetry only for dependency management but not for packaging, you can use the **non-package mode**: ``` [tool.poetry] package-mode = false ``` In this mode, metadata such as `name` and `version` are optional. Therefore, it is not possible to build a distribution or publish the project to a package index. Further, when running `poetry install`, Poetry does not try to install the project itself, but only its dependencies (same as `poetry install --no-root`). ### Specifying dependencies [\#](https://python-poetry.org/docs/basic-usage/#specifying-dependencies) If you want to add dependencies to your project, you can specify them in the `project` section. ``` [project] # ... dependencies = [ "pendulum (>=2.1,<3.0)" ] ``` As you can see, it takes a mapping of **package names** and **version constraints**. Poetry uses this information to search for the right set of files in package “repositories” that you register in the `tool.poetry.source` section, or on [PyPI](https://pypi.org/) by default. Also, instead of modifying the `pyproject.toml` file by hand, you can use the `add` command. ``` $ poetry add pendulum ``` It will automatically find a suitable version constraint **and install** the package and sub-dependencies. Poetry supports a rich [dependency specification](https://python-poetry.org/docs/dependency-specification/) syntax, including caret, tilde, wildcard, inequality and [multiple constraints](https://python-poetry.org/docs/dependency-specification/#multiple-constraints-dependencies) requirements. ## Using your virtual environment [\#](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment) By default, Poetry creates a virtual environment in `{cache-dir}/virtualenvs`. You can change the [`cache-dir`](https://python-poetry.org/docs/configuration/#cache-dir "cache-dir configuration documentation") value by editing the Poetry configuration. Additionally, you can use the [`virtualenvs.in-project`](https://python-poetry.org/docs/configuration/#virtualenvsin-project) configuration variable to create virtual environments within your project directory. There are several ways to run commands within this virtual environment. Note **External virtual environment management** Poetry will detect and respect an existing virtual environment that has been externally activated. This is a powerful mechanism that is intended to be an alternative to Poetry’s built-in, simplified environment management. To take advantage of this, simply activate a virtual environment using your preferred method or tooling, before running any Poetry commands that expect to manipulate an environment. ### Using `poetry run` [\#](https://python-poetry.org/docs/basic-usage/#using-poetry-run) To run your script simply use `poetry run python your_script.py`. Likewise if you have command line tools such as `pytest` or `black` you can run them using `poetry run pytest`. Note If managing your own virtual environment externally, you do not need to use `poetry run` since you will, presumably, already have activated that virtual environment and made available the correct python instance. For example, these commands should output the same python path: ``` conda activate your_env_name which python poetry run which python eval "$(poetry env activate)" which python ``` ### Activating the virtual environment [\#](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment) See [Activating the virtual environment](https://python-poetry.org/docs/managing-environments/#activating-the-environment). ## Version constraints [\#](https://python-poetry.org/docs/basic-usage/#version-constraints) In our example, we are requesting the `pendulum` 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 read [Dependency specification](https://python-poetry.org/docs/dependency-specification/ "Dependency specification documentation") for more in-depth information on versions, how versions relate to each other, and on the different ways you can specify dependencies. Note **How does Poetry download the right files?** When you specify a dependency in `pyproject.toml`, Poetry first takes the name of the package that you have requested and searches for it in any repository you have registered using the `repositories` key. If you have not registered any extra repositories, or it does not find a package with that name in the repositories you have specified, it falls back to PyPI. When Poetry finds the right package, it then attempts to find the best match for the version constraint you have specified. ## Installing dependencies [\#](https://python-poetry.org/docs/basic-usage/#installing-dependencies) To install the defined dependencies for your project, just run the [`install`](https://python-poetry.org/docs/cli/#install) command. ``` poetry install ``` When you run this command, one of two things may happen: ### Installing without `poetry.lock` [\#](https://python-poetry.org/docs/basic-usage/#installing-without-poetrylock) If you have never run the command before and there is also no `poetry.lock` file present, Poetry simply resolves all dependencies listed in your `pyproject.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 the `poetry.lock` file, locking the project to those specific versions. You should commit the `poetry.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 with `poetry.lock` [\#](https://python-poetry.org/docs/basic-usage/#installing-with-poetrylock) This brings us to the second scenario. If there is already a `poetry.lock` file as well as a `pyproject.toml` file when you run `poetry install`, it means either you ran the `install` command before, or someone else on the project ran the `install` command and committed the `poetry.lock` file to the project (which is good). Either way, running `install` when a `poetry.lock` file is present resolves and installs all dependencies that you listed in `pyproject.toml`, but Poetry uses the exact versions listed in `poetry.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 your `pyproject.toml` file, but they may not all be at the very latest available versions (some dependencies listed in the `poetry.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 your `poetry.lock` file to version control [\#](https://python-poetry.org/docs/basic-usage/#committing-your-poetrylock-file-to-version-control) #### As an application developer [\#](https://python-poetry.org/docs/basic-usage/#as-an-application-developer) Application developers commit `poetry.lock` to get more reproducible builds. Committing this file to VC is important because it will cause anyone who sets up the project to 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 confident the dependencies installed are still working even if your dependencies released many new versions since then. (See note below about using the update command.) Warning If you have added the recommended [`[build-system]`](https://python-poetry.org/docs/pyproject/#poetry-and-pep-517) section to your project’s pyproject.toml then you *can* successfully install your project and its dependencies into a virtual environment using a command like `pip install -e .`. However, pip will not use the lock file to determine dependency versions as the poetry-core build system is intended for library developers (see next section). #### As a library developer [\#](https://python-poetry.org/docs/basic-usage/#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 your `pyproject.toml`. The application will probably use the latest compatible dependency version. If your library’s `poetry.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 the `poetry.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 if `poetry.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 of `poetry.lock` to stay up-to-date and reduce the risk of sudden breakage for users. ### Installing dependencies only [\#](https://python-poetry.org/docs/basic-usage/#installing-dependencies-only) The current project is installed in [editable](https://pip.pypa.io/en/stable/topics/local-project-installs/) mode by default. If you want to install the dependencies only, run the `install` command with the `--no-root` flag: ``` poetry install --no-root ``` ## Updating dependencies to their latest versions [\#](https://python-poetry.org/docs/basic-usage/#updating-dependencies-to-their-latest-versions) As mentioned above, the `poetry.lock` file prevents you from automatically getting the latest versions of your dependencies. To update to the latest versions, use the `update` command. This will fetch the latest matching versions (according to your `pyproject.toml` file) and update the lock file with the new versions. (This is equivalent to deleting the `poetry.lock` file and running `install` again.) Note Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml` are not synchronized.