Commands You’ve already learned how to use the command-line interface to do some things. This chapter documents all the available commands. To get help from the command-line, simply call poetry to see the complete list of commands, then --help combined with any of those can give you more information. Global options --verbose (-v|vv|vvv): Increase the verbosity of messages: “-v” for normal output, “-vv” for more verbose output and “-vvv” for debug. --help (-h) : Display help information. --quiet (-q) : Do not output any message. --ansi: Force ANSI output. --no-ansi: Disable ANSI output. --version (-V): Display this application version. --no-interaction (-n): Do not ask any interactive question. --no-plugins: Disables plugins. --no-cache: Disables Poetry source caches. --directory=DIRECTORY (-C): The working directory for the Poetry command (defaults to the current working directory). new This command will help you kickstart your new Python project by creating a directory structure suitable for most projects.

The pyproject.toml file The tool.poetry section of the pyproject.toml file is composed of multiple sections. name The name of the package. Required This should be a valid name as defined by PEP 508. name = "my-package" version The version of the package. Required This should be a valid PEP 440 string. version = "0.1.0" Note If you would like to use semantic versioning for your project, please see here. description A short description of the package. Required

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. This file can typically be found in one of the following directories: macOS: ~/Library/Application Support/pypoetry Windows: %APPDATA%\pypoetry For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME. That means, by default ~/.config/pypoetry. Local configuration Poetry also provides the ability to have settings that are specific to a project by passing the --local option to the config command.

The pyproject.toml file The tool.poetry section of the pyproject.toml file is composed of multiple sections. package-mode Whether Poetry operates in package mode (default) or not. Optional See basic usage for more information. package-mode = false name The name of the package. Required in package mode This should be a valid name as defined by PEP 508. name = "my-package" version The version of the package. Required in package mode This should be a valid PEP 440 string.

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. This file can typically be found in one of the following directories: macOS: ~/Library/Application Support/pypoetry Windows: %APPDATA%\pypoetry For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME. That means, by default ~/.config/pypoetry. Local configuration Poetry also provides the ability to have settings that are specific to a project by passing the --local option to the config command.

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. But, you want to install a dependency to your project for a simple API repository? Let’s do it.

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). Other fields are optional. In non-package mode, the name and version fields are required if using the project section. Note Run poetry check to print warnings about deprecated fields. The project section The project section of the pyproject.toml file according to the specification of the PyPA. name The name of the package. Always required when the project section is specified

Managing dependencies Poetry supports specifying main dependencies in the project.dependencies section of your pyproject.toml according to PEP 621. For legacy reasons and to define additional information that are only used by Poetry the tool.poetry.dependencies sections can be used. See Dependency specification for more information. Dependency groups Poetry provides a way to organize your dependencies by groups. The dependencies declared in project.dependencies respectively tool.poetry.dependencies are part of an implicit main group. Those dependencies are required by your project during runtime.

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. To achieve this, it will first check if it’s currently running inside a virtual environment. If it is, it will use it directly without creating a new one. But if it’s not, it will use one that it has already created or create a brand new one for you.

Community Badge For any projects using Poetry, you may add its official badge somewhere prominent like the README. Markdown [](https://python-poetry.org/) reStructuredText .. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json :alt: Poetry :target: https://python-poetry.org/