Install poetry using pip

Install Poetry into a (normal) Django app — step-by-step

0) Quick prerequisites — check Python

Make sure you have a supported Python (Poetry expects a recent Python; check your local version):

python3 --version

Poetry’s docs require modern Python (3.9+ for recent Poetry releases). ([python-poetry.org][1])

---

1) Install Poetry (two safe options)

Option A — recommended (pipx) — isolates Poetry and makes upgrading easy:

python -m pip install --user pipx
python -m pipx ensurepath      # then restart your shell if prompted
pipx install poetry

pipx installs CLI tools into isolated environments (recommended for tools like Poetry). ([python-poetry.org][1])

Option B — official installer script (works on Linux/macOS/Windows PowerShell):

Unix / WSL / macOS:

curl -sSL https://install.python-poetry.org | python3 -

Windows PowerShell:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

This is Poetry’s official installer (the script will tell you if you need to add Poetry’s bin directory to your PATH). ([install.python-poetry.org][2])

After install, verify:

poetry --version

---

2) Fix PATH if poetry is not found

If poetry --version fails, the installer will have printed the bin dir (e.g. ~/.local/bin on Unix or %APPDATA%\Python\Scripts on Windows). Add that to your PATH (or follow the installer’s message). ([install.python-poetry.org][2])

---

3) (Optional but recommended) make Poetry create .venv inside the project

If you want each project to have its virtualenv inside the project directory (nice for editors, Docker, portability):

poetry config virtualenvs.in-project true

This makes Poetry create .venv/ in your project root when you run poetry install. (You can still change it later.) ([python-poetry.org][3])

Add .venv/ to your .gitignore:

echo ".venv/" >> .gitignore

---

4) Convert or initialize Poetry in your Django project

If you have an existing project (recommended):

From your project root:

cd /path/to/your-django-project
poetry init

poetry init launches an interactive prompt to create pyproject.toml. If you prefer noninteractive:

poetry init --no-interaction

Then add dependencies (next step). pyproject.toml + poetry.lock are the files you commit to git. ([browniebroke.com][4])

If you’re starting a brand-new project with Poetry:

mkdir mysite && cd mysite
poetry new --src mysite          # optional: creates package scaffolding
poetry init --no-interaction

---

5) Add Django (and other packages)

Install Django into the poetry-managed environment:

poetry add django

Add dev tools (example):

poetry add --group dev pytest pytest-django black isort

If you have an existing requirements.txt, you can either add packages one by one (safer):

poetry add package1 package2

or (less recommended — test after) import them in bulk on Unix:

xargs -n1 poetry add < requirements.txt

Poetry updates pyproject.toml and poetry.lock automatically. ([rasulkireev.com][5])

---

6) Create the virtualenv and install dependencies

Now install everything and create the venv:

poetry install

If you only want to install dependencies (not install your project package in editable mode), use:

poetry install --no-root

(Handy for certain Docker or CI flows.) ([Stack Overflow][6])

---

7) Use the Poetry virtualenv to run Django commands

Two ways:

• Run a single command inside Poetry’s venv:

poetry run python manage.py migrate
poetry run python manage.py runserver

• Or spawn a shell within the venv:

poetry shell
python manage.py runserver
# exit when done
exit

poetry run <cmd> and poetry shell are the usual ways to run/manage your Django app with Poetry. ([Stack Overflow][7])

---

8) Pin specific Python interpreter (if needed)

If Poetry picked the wrong Python, tell Poetry explicitly which python to use:

poetry env use /usr/bin/python3.11
# or
poetry env use python3.11

This is useful when your team uses pyenv or you want to lock to a specific interpreter. ([python-poetry.org][8])

---

9) Commit and workflow notes

• Commit pyproject.toml and poetry.lock to git (they replace requirements.txt as the canonical dependency spec).
• Add .venv/ to .gitignore if using in-project venv.
• Use poetry add / poetry remove to change deps; commit poetry.lock after changes.
• To update lockfile without changing versions (rare) use poetry lock --no-update. To update deps use poetry update package-name. ([Stack Overflow][9])

---

10) Deploying / CI

Many PaaS/CI systems expect a requirements.txt. You can export one from Poetry when needed:

poetry export --without-hashes --format=requirements.txt --output=requirements.txt

(Use --without dev or flags as needed.) Alternatively, many modern hosts support installing with Poetry directly. ([TestDriven.io][10])

---

11) Upgrading Poetry itself

• If you installed with pipx: pipx upgrade poetry
• If you used the official installer: poetry self update

(Behavior can differ depending on how you installed Poetry.) ([python-poetry.org][1])

---

Common gotchas & tips

• If poetry is not found after install, add the printed bin dir to PATH. ([install.python-poetry.org][2])
• If Django commands aren’t found, use poetry run or poetry shell so the venv’s django-admin / python are used. ([Stack Overflow][7])
• Prefer adding deps with poetry add rather than editing pyproject.toml by hand (Poetry will keep the lockfile consistent).

---