Managing a Django Project with Poetry
Update (02/03/2022): I wrote an updated guide on how to create a django project with poetry for the builtwithdjango site. It focuses on creating a project with poetry. In the future I will also write a guide on how to migrate a project to poetry.
Poetry is relatively new packaging and dependency manager. It makes it very easy to upload libraries to PyPI, manage dependencies visually, and has a couple of handy features. Today, I’m not going to do a deep dive into how Poetry works and all its features. Today I just want to focus on configuring a Django project.
1. Install Poetry
For Linux, macOS or WSL, use the official Poetry installer:
curl -sSL https://install.python-poetry.org | python3 -If poetry is not found afterward, follow the installation guide’s PATH instructions for your platform.
2. Create a Directory for you Django Project
mkdir django_poetry_example && cd django_poetry_example3. Initiate a Poetry Project
poetry initYou will be asked to confirm the information about your project. You can skip through most of it.
The output below is from the original walkthrough; current Poetry versions may prompt differently.
This command will guide you through creating your pyproject.toml config.
Package name [django_poetry_example]:
Version [0.1.0]:
Description []:
Author [Rasul Kireev <rasul.kireev@guycarp.com>, n to skip]:
License []:
Compatible Python versions [^3.7]:
Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no
Generated file
[tool.poetry]
name = "django_poetry_example"
version = "0.1.0"
description = ""
authors = []
[tool.poetry.dependencies]
python = "^3.7"
[tool.poetry.dev-dependencies]
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
Do you confirm generation? (yes/no) [yes]4. Add the Necessary Dependencies
Run poetry add django in your terminal. Poetry will add django to the pyproject.toml file under the dependencies section. A virtual environment will also be created for you.
5. Start you Django Project
poetry run django-admin startproject django_poetry_example .6. Working on your Django Project
When you need to run any python function (for example, python manage.py createsuperuser) you have two options.
- You can leverage
poetry run, which will run against the current project’s dependencies. The command will be this:poetry run python manage.py createsuperuser. - You can activate the virtual environment with a
poetry shellcommand. With Poetry 2.x, first install the shell plugin withpoetry self add poetry-plugin-shell. Now you can run python commands, as is. They will be run with dependencies you have installed.
I prefer the first method, for an explicit approach.
Bonus. Export dependencies to a requirements.txt
If you need to have the requirements.txt file with all the dependencies, you can run poetry export -f requirements.txt --output requirements.txt. With Poetry 2.x, first install the export plugin with poetry self add poetry-plugin-export; it is no longer included by default. If you have configured a CI/CD job that auto deploys your project, you can add this function as a step, which will generate the updated version on each update.
Bonus II. Video
If you prefer a more visual approach, I have made a video that shows how to start a Django project with Poetry.