In this guide, I’ll walk through setting up a brand new Django project with the awesome Poetry dependency manager for Python.

Poetry

Poetry is a dependency manager for Python projects, much in the vein of Bundler for Ruby, or Yarn for JavaScript. I’ll be using it to set up the Django project and adding the modules needed for the Jet Admin theme. Poetry has great documentation on their site, so if you run into issues head over there for some help.

Installing

The following is taken straight from the Poetry installation docs at the time of writing.

macOS / Linux

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python

 Windows Powershell

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python

Initalise a new project

Once you have Poetry installed, we can use it to create a new project. Poetry projects are not just for Django web apps, but for anything you want to build in Python. It’s a great way to create your projects and manage the third-party tools you want to use.

Start off creating a new directory for your project. I make an assumption here that you have a code directory in your home path. Also, from this point out the commands are based on the *nix / macOS environment I’m most familiar with.

cd ~/code/
mkdir demoproject

Now change your working directory to the new project path you just created, and use Poetry to initialise the project.

cd demoproject
poetry init

Running the init command will take you into an interactive session to define the parameters of your new project. Pressing enter on each question will use the defaults (in the []). You can use the init session to define your dependencies right here, but I have skipped that to use other Poetry commands as we configure our project.

This command will guide you through creating your pyproject.toml config.

Package name [demoproject]:
Version [0.1.0]:
Description []:
Author [user <user@example.com>, n to skip]:
License []:
Compatible Python versions [^3.7]:

Would you like to define your main dependencies interactively? (yes/no) [yes]
You can specify a package in the following forms:
  - A single name (requests)
  - A name and a constraint (requests ^2.23.0)
  - A git url (git+https://github.com/python-poetry/poetry.git)
  - A git url with a revision (git+https://github.com/python-poetry/poetry.git#develop)
  - A file path (../my-package/my-package.whl)
  - A directory (../my-package/)
  - An url (https://example.com/packages/my-package-0.1.0.tar.gz)

Search for package to add (or leave blank to continue):

Would you like to define your development dependencies interactively? (yes/no) [yes]
Search for package to add (or leave blank to continue):

Generated file

[tool.poetry]
name = "demoproject"
version = "0.1.0"
description = ""
authors = ["user <user@example.com>"]

[tool.poetry.dependencies]
python = "^3.7"

[tool.poetry.dev-dependencies]

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"


Do you confirm generation? (yes/no) [yes]

On confirmation, Poetry writes the generated file content to a pyproject.toml file in your project directory. This is what you use to tell Poetry what your project looks like, for example stating the version of Python to use for the project. The ^3.7 stands for “any version from 3.7 up to but not including 4.0”. This means that my project should work with all minor and patch version of Python 3. The full list of versioning for Poetry dependencies can be found on their documentation.

Django

Next up we’re going to add Django as a dependency of the demo project. From here on out we’ll be using Poetry to add these packages. Run the following command in your demo project directory.

poetry add django

You should get something like the following output:

Versions numbers may be different, but it should be fairly similar. The thing to note here is that as Django is the first package we add, Poetry will also configure the virtual environment for our project. You will also notice that Poetry writes a poetry.lock file to the demo project dir. You can read more about it on the Poetry docs for lock files, this file should be commited to ensure everyone on the project uses the exact same dependencies.

Creating virtualenv demoproject in /Users/dave/Code/python-stuff/demoproject/.venv
Using version ^3.0.8 for django

Updating dependencies
Resolving dependencies... (0.2s)

Writing lock file


Package operations: 4 installs, 0 updates, 0 removals

  - Installing asgiref (3.2.10)
  - Installing pytz (2020.1)
  - Installing sqlparse (0.3.1)
  - Installing django (3.0.8)

Now that we have Django installed we can start a new project using the django-admin command. As the package is installed via Poetry we pass commands to Django via Poetry. Run the following to start the Django project.

poetry run django-admin.py startproject demoproject .

If you explore your demo project directory it should now look something like this. For those of you familiar with Django already this should look just like a fresh Django app directory.

.
├── demoproject
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py
├── poetry.lock
└── pyproject.toml

And, you’re done. You have a fresh Django project set up and configured with Poetry. You can build your web application following the normal Django path. The only difference is that any packages you want to add, you use the poetry add command rather than pip.

Useful commands:

poetry init - start a new Poetry project and create a virtual environment

poetry add - add a new depenedency and install it in the current virtual environment

poetry install - use the lock file to install all dependencies