Skip to main content

​
pyproject.toml file for Python

The pyproject.toml file is a modern way to specify all your project’s build system requirements and dependencies in a single file. This guide shows how to create, configure and use pyproject.toml to ensure consistency between development and production environments.

​
What is a pyproject.toml file?

A pyproject.toml lists dependencies, build system and other metadata for your Python project. This allows:
  • You and your team to maintain identical environments
  • New collaborators to reproduce the environment exactly
  • Set up development and production dependencies separately
1

Create the pyproject.toml file

First, create a file named pyproject.toml in the root of your project.
2

Define your project details

In the pyproject.toml file, start by defining your project metadata. We will define the project name, version, description, and other relevant information.
The project name must consist of ASCII letters, digits, underscores “_”, hyphens “-” and periods “.”. It must not start or end with an underscore, hyphen or period. For example:
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
3

List project dependencies

Next, we will list the dependencies required for our project. We can specify both development and production dependencies. The production dependencies are listed under the dependencies section, while development dependencies can be listed under optional-dependencies with a specific group name (e.g., dev).
You can specify versions for your dependencies using comparison operators like ==, >=, <… In the example below, we do not specify versions. This means that the latest will be installed. It is recommended to specify exact versions to ensure reproducibility and prevent breakage from incompatible updates in production.
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
dependencies = [
    "discord-py",
    "aiohttp"
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]
4

Set up the build system

Finally, we need to specify the build system requirements. This is necessary for tools like pip to know how to build and install your project. We will use setuptools as our build backend, which is a common choice for Python projects, but you can choose others like poetry.
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
dependencies = [
    "discord.py",
    "aiohttp"
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

​
Install dependencies with pip

To install the dependencies listed in your pyproject.toml file, you can use pip or other tools that support pyproject.toml. This allows you to work on your project while having the dependencies installed. 
pip install .
This command will read the pyproject.toml file, install the dependencies listed under dependencies, and set up your project for development. If you want to install the development dependencies as well, you can use: 
pip install .[dev]
This will install both the production and development dependencies, allowing you to work on your project with all the necessary tools.

​
Best practices and tips:

  • Keep updated: Review and update pyproject.toml regularly as you add new dependencies
  • Use exact versions: Always use == instead of >, >= or no version to avoid surprises in production
  • Versioning: Commit pyproject.toml to git to track dependency changes and version updates
  • Isolated environment: Maintain one virtual environment per project to avoid global conflicts
  • Test locally: Before deploying, test the file with pip install . in a new environment

​
Next steps

With your pyproject.toml file configured:
  1. Commit to your Git repository.
  2. Host your project on Square Cloud.
  3. Configure automatic deploy via GitHub.
  4. Welcome to professional Python application hosting!
A well-structured pyproject.toml file is the foundation for any successful Python application, ensuring your application works perfectly on Square Cloud.