pip install from pyproject.toml (With Examples)

For a pip install from pyproject.toml, open a terminal in the folder that holds the file and run pip install .. The dot means “this project”: pip reads pyproject.toml, builds the package and installs it along with its dependencies:

pip install .            # install the project and its dependencies
pip install -e .         # editable install while you develop
pip install --group dev  # a dependency group (pip 25.1+)

I tested every command on a tiny invoice project inside a fresh virtual environment, using Python 3.12.5 and pip 26.2.1.

We’ll look at the pyproject.toml file, install it normally and in editable mode, add optional extras and dependency groups, and fix the two mistakes I see most often.

The pyproject.toml used in this example

Here’s the sample project. It uses a src layout, with cli.py inside src/invoice_tool/:

  • [build-system] tells pip which build backend to use (setuptools here).
  • [project] holds the name, version and dependencies.
  • [project.optional-dependencies] defines extras like excel.
  • [project.scripts] creates an invoice-total command.
  • [dependency-groups] lists tools you only need while developing.

pip install from pyproject.toml with pip install .

Run it from the project folder. pip creates an isolated build environment, installs setuptools there, builds a wheel, then installs it with tabulate:

# pyproject.toml
[build-system]
requires = ["setuptools>=77"]
build-backend = "setuptools.build_meta"

[project]
name = "invoice-tool"
version = "1.0.0"
requires-python = ">=3.10"
dependencies = ["tabulate>=0.9"]

[project.optional-dependencies]
excel = ["openpyxl>=3.1"]

[project.scripts]
invoice-total = "invoice_tool.cli:main"

[dependency-groups]
dev = ["pytest>=8"]

Output:

pip 26.2.1 from C:\pyguides\invoice_tool\.venv\Lib\site-packages\pip (python 3.12)
Processing .\.
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: started
  Getting requirements to build wheel: finished with status 'done'
  Preparing metadata (pyproject.toml): started
  Preparing metadata (pyproject.toml): finished with status 'done'
Collecting tabulate>=0.9 (from invoice-tool==1.0.0)
  Using cached tabulate-0.10.0-py3-none-any.whl.metadata (40 kB)
Using cached tabulate-0.10.0-py3-none-any.whl (39 kB)
Building wheels for collected packages: invoice-tool
  Building wheel for invoice-tool (pyproject.toml): started
  Building wheel for invoice-tool (pyproject.toml): finished with status 'done'
  Created wheel for invoice-tool: filename=invoice_tool-1.0.0-py3-none-any.whl size=1975 sha256=ba92e0b6dd7b8012507fffb0ae713b686d545b87f93a2bd1bb0fb1f83bbb7f37
  Stored in directory: C:\pyguides\tmp\pip-ephem-wheel-cache-lw6j3_tj\wheels\98\54\05\08aa4defe5318fe92b7515e7ed19a222bcd294e87b7e5725f9
Successfully built invoice-tool
Installing collected packages: tabulate, invoice-tool

Successfully installed invoice-tool-1.0.0 tabulate-0.10.0
Line    Amount
------  --------
Item 1  $19.99
Item 2  $5.25
Item 3  $102.00
Tax     $10.50
Total   $137.74
Command Prompt output of pip install . building and installing a project from pyproject.toml, then running its console script
pip built the wheel, pulled in tabulate, and the invoice-total command works straight away.

Always run this inside a virtual environment so the project doesn’t land in your global Python. See Python virtual environments if you haven’t set one up.

Editable install and optional dependencies

While you’re working on the code, pip install -e . links the project instead of copying it, so edits show up without reinstalling. Add extras in square brackets, with quotes:

import sys
from tabulate import tabulate

TAX_RATE = 0.0825                      # Austin, TX sales tax

def total(prices):
    subtotal = round(sum(prices), 2)
    return subtotal, round(subtotal * TAX_RATE, 2)

def main():
    prices = [float(p) for p in sys.argv[1:]]
    subtotal, tax = total(prices)
    rows = [[f"Item {i}", f"${p:,.2f}"] for i, p in enumerate(prices, 1)]
    rows += [["Tax", f"${tax:,.2f}"], ["Total", f"${subtotal + tax:,.2f}"]]
    print(tabulate(rows, headers=["Line", "Amount"], tablefmt="simple"))

Output:

Obtaining file:///C:/pyguides/invoice_tool
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Checking if build backend supports build_editable: started
  Checking if build backend supports build_editable: finished with status 'done'
  Getting requirements to build editable: started
  Getting requirements to build editable: finished with status 'done'
  Preparing editable metadata (pyproject.toml): started
  Preparing editable metadata (pyproject.toml): finished with status 'done'
Requirement already satisfied: tabulate>=0.9 in .\.venv\Lib\site-packages (from invoice-tool==1.0.0) (0.10.0)
Collecting openpyxl>=3.1 (from invoice-tool==1.0.0)
  Using cached openpyxl-3.1.5-py2.py3-none-any.whl.metadata (2.5 kB)
Collecting et-xmlfile (from openpyxl>=3.1->invoice-tool==1.0.0)
  Using cached et_xmlfile-2.0.0-py3-none-any.whl.metadata (2.7 kB)
Using cached openpyxl-3.1.5-py2.py3-none-any.whl (250 kB)
Using cached et_xmlfile-2.0.0-py3-none-any.whl (18 kB)
Building wheels for collected packages: invoice-tool
  Building editable for invoice-tool (pyproject.toml): started
  Building editable for invoice-tool (pyproject.toml): finished with status 'done'
  Created wheel for invoice-tool: filename=invoice_tool-1.0.0-0.editable-py3-none-any.whl size=1576 sha256=7e7b12bdee162b0f551c6ea3f65451f2aaaa370f20b49fd24e59c438b1d8b1d0
  Stored in directory: C:\pyguides\tmp\pip-ephem-wheel-cache-63kdvo8n\wheels\98\54\05\08aa4defe5318fe92b7515e7ed19a222bcd294e87b7e5725f9
Successfully built invoice-tool
Installing collected packages: invoice-tool, et-xmlfile, openpyxl
  Attempting uninstall: invoice-tool
    Found existing installation: invoice-tool 1.0.0
    Uninstalling invoice-tool-1.0.0:
      Successfully uninstalled invoice-tool-1.0.0

Successfully installed et-xmlfile-2.0.0 invoice-tool-1.0.0 openpyxl-3.1.5
invoice-tool 1.0.0   C:\pyguides\invoice_tool
openpyxl     3.1.5
tabulate     0.10.0
Command Prompt output of pip install -e with an excel extra from pyproject.toml and pip list showing the editable project location
pip list shows the editable location and the openpyxl extra that came with [excel].

The quotes around ".[excel]" matter in PowerShell and zsh, which treat square brackets specially. Pinning works the same as elsewhere; see pip install a specific version.

How do you install a dependency group with pip?

Dependency groups (PEP 735) hold things like test tools that aren’t part of your package. pip 25.1 added --group, which installs a group without building the project:

from invoice_tool.cli import total

def test_total_adds_texas_tax():
    assert total([19.99, 5.25, 102.00]) == (127.24, 10.5)

Output:

Collecting pytest>=8
  Using cached pytest-9.1.1-py3-none-any.whl.metadata (7.6 kB)
Collecting colorama>=0.4 (from pytest>=8)
  Using cached colorama-0.4.6-py2.py3-none-any.whl.metadata (17 kB)
Collecting iniconfig>=1.0.1 (from pytest>=8)
  Using cached iniconfig-2.3.0-py3-none-any.whl.metadata (2.5 kB)
Collecting packaging>=22 (from pytest>=8)
  Using cached packaging-26.3-py3-none-any.whl.metadata (3.5 kB)
Collecting pluggy<2,>=1.5 (from pytest>=8)
  Using cached pluggy-1.6.0-py3-none-any.whl.metadata (4.8 kB)
Collecting pygments>=2.7.2 (from pytest>=8)
  Using cached pygments-2.21.0-py3-none-any.whl.metadata (2.5 kB)
Using cached pytest-9.1.1-py3-none-any.whl (386 kB)
Using cached pluggy-1.6.0-py3-none-any.whl (20 kB)
Using cached colorama-0.4.6-py2.py3-none-any.whl (25 kB)
Using cached iniconfig-2.3.0-py3-none-any.whl (7.5 kB)
Using cached packaging-26.3-py3-none-any.whl (129 kB)
Using cached pygments-2.21.0-py3-none-any.whl (1.3 MB)
Installing collected packages: pygments, pluggy, packaging, iniconfig, colorama, pytest

Successfully installed colorama-0.4.6 iniconfig-2.3.0 packaging-26.3 pluggy-1.6.0 pygments-2.21.0 pytest-9.1.1
.                                                                        [100%]
1 passed in 0.02s
Command Prompt output of pip install --group dev installing pytest from pyproject.toml dependency groups and a passing test
The dev group installed pytest, and the test passed against the editable install.

If you see no such option: --group, your pip is older; upgrade it with python -m pip install --upgrade pip.

Common pyproject.toml install mistakes

Two errors come up constantly. -r is only for requirements files, and pip install . needs a folder that actually has a pyproject.toml or setup.py:

ship invoice tool

Output:

ERROR: Invalid requirement: '[build-system]': Expected package name at the start of dependency specifier
    [build-system]
    ^ (from line 1 of pyproject.toml)
ERROR: Directory './notes' is not installable. Neither 'setup.py' nor 'pyproject.toml' found.
Command Prompt output of pip install -r pyproject.toml failing with an invalid requirement error and pip install on a folder with no pyproject.toml
Neither command can work: the first passes TOML to a requirements parser, the second points at a folder with no project file.

Requirements files still have their place for pinned app installs; see pip install -r requirements.txt. If an import fails after a successful install, check ModuleNotFoundError after pip install.

Can pip install only the dependencies from pyproject.toml?

pip doesn’t have an option that installs [project] dependencies while skipping the project itself. The usual approaches are an editable install, a dependency group, or exporting to a requirements file with a tool like uv or pip-tools.

pyproject.toml install commands at a glance

CommandWhat it does
pip install .Build and install the project with its dependencies
pip install -e .Editable install for development
pip install ".[excel]"Install with an optional extra
pip install --group devInstall a dependency group (pip 25.1+)
pip install path/to/projectInstall a project from another folder

More guides on pip and Python packages:

Frequently asked questions

How do I pip install from pyproject.toml?

Open a terminal in the project folder and run pip install .. pip reads pyproject.toml, builds the package and installs it with its dependencies.

Can I use pip install -r pyproject.toml?

No. -r expects a requirements file, so pip fails with an invalid requirement error. Use pip install . instead.

What does pip install -e . do?

It installs the project in editable mode, so code changes take effect without reinstalling.

How do I install optional dependencies?

Put the extra in brackets with quotes: pip install ".[excel]".

How do I install a dependency group?

Run pip install --group dev with pip 25.1 or newer.

Where is pip install documented?

See pip install in the pip documentation.