In this guide, I’ll walk through setting up a brand new Django project with the awesome Poetry dependency manager for Python.
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
(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
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 <email@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 <firstname.lastname@example.org>"] [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.
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
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