Jordi Smit
Machine Learning Engineer
27 Jul 2022 3 min read

Poetry cheatsheet

Poetry is an awsome dependency management and virtual environment management tool for Python. I use it quite often in my day-to-day work. If you are a PIP or Conda user, you might find that Poetry’s CLI is slightly different from what you are used to. So to help you get started I created overview of the command I use most often.

Project creation

poetry new my-packageThis creates a new project. This new project will contain a new pyproject.toml and files. It also sets up the folder structure for your Python package and your unit tests.
poetry new --src my-packageThis also creates a new project but with the src project layout.
poetry initThis creates a new pyproject.toml file without creating an entire folder structure.

Dependancy management

poetry installThis installs all the dependencies that are specified in the poetry.lock file. Thus, if you change your pyproject.toml but you do not update your poetry.lock file it will install the dependencies as specified in the (outdated) poetry.lock file. If there is no poetry.lock file, it will automatically first run the poetry lock command to create a poetry.lock file.
poetry install --no-devThis only installs the main dependencies and does not install the development dependencies. Your dev dependencies are dependencies that you don’t need to run the application such as pytest, mypy, etc. So, if you don’t install them your final application will take up less space.
poetry install --remove-untrackedRemoves all dependencies that are installed in your venv but are no longer specified in your poetry.lock file.
poetry install --extras "NAME_1 NAME_NThis installs the optional dependencies NAME_1 and NAME_N.
poetry install --no-rootThis installs your projects dependencies but doesn’t install your package to the global name space in the venv. Thus, you can no longer directly import the package you made.
poetry updateUpdate all the dependencies in the poetry.lock file to their latest version.
poetry update NAME_1 NAME_2Updates only NAME_1 and NAME_N in the poetry.lock file to their latest version.
poetry add NAME_1 NAME_2Adds NAME_1 and NAME_N to the poetry.lock file and installs them into the venv. You can also add constrains like @^2.0.5, >=2.0.5 or <=2.0.5.
poetry add ../path/to/other/folder/with/pyproject.tomlAdds another poetry project as a local dependency. This is quite usefull for mono-repos.
poety remove NAME_1 NAME_2Uninstalls dependency NAME_1 and NAME_N from the VENV. Also removes them from the poetry.lock file.
poetry lockIf you have updated the dependencies in the pyproject.toml file manually, you can use this command to update the poetry.lock file.
poetry export -f requirements.txt --output requirements.txtExport the lock file in the traditional requirements.txt file format.

Virtual environment

poetry run CMDRun a command inside the virtual environment without activating the VENV. For example, CMD can be python, black, pytest, etc.
poetry shellActivates the virtual environment. Similar to conda activate name or source venv/bin/activate.
poetry env use path/to/pythonNTell poetry to use the python version at path/to/pythonN as a basis for the VENV. You need this if you want to use a specific python version for VENV, e.g. py3.9 or py3.10.
poetry env info --pathThis gives the absolute path to the virtual environment. Useful if your IDEA needs a path to your python interpreter.
poetry env remove /full/path/to/pythonThis deletes the virtual environment.
poetry config trueTell poetry to save the VENV dir in the same directory as the pyproject.toml.

For a more complete overview I recommend you to read the Poetry documentation.