> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Create a pyproject.toml File

> Create a pyproject.toml for a Python app: declare project metadata, pinned dependencies and a build system so Square Cloud can install it with pip.

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

***

<Steps>
  <Step title="Create the pyproject.toml file">
    First, create a file named `pyproject.toml` in the root of your project.
  </Step>

  <Step title="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:

    ```toml pyproject.toml theme={"system"}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    ```
  </Step>

  <Step title="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, every dependency is pinned to an exact version with `==`.
    It is recommended to specify exact versions to ensure reproducibility and prevent breakage from incompatible updates in production.

    ```toml pyproject.toml theme={"system"}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord.py==2.7.1",
        "aiohttp==3.14.3"
    ]

    [project.optional-dependencies]
    dev = [
        "pytest==9.1.1",
        "black==26.5.1"
    ]
    ```
  </Step>

  <Step title="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`.
    The `py-modules = []` line under `[tool.setuptools]` tells setuptools that there is no module to package, so `pip install .` only installs the dependencies. Without it, an app with several top-level folders (for example `cogs/` and `utils/`) fails with `Multiple top-level packages discovered in a flat-layout`.

    ```toml pyproject.toml theme={"system"}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    dependencies = [
        "discord.py==2.7.1",
        "aiohttp==3.14.3"
    ]

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

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

    [tool.setuptools]
    py-modules = []
    ```
  </Step>
</Steps>

***

## 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.

```bash theme={"system"}
pip install .
```

This command will read the `pyproject.toml` file, install the dependencies listed under `dependencies`, and set up your project for development. It is also what Square Cloud runs when your upload has a `pyproject.toml` and no `requirements.txt`. If you want to install the development dependencies as well, you can use:

```bash theme={"system"}
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 it to your Git repository.
2. Host your project with the [Python runtime guide](/en/articles/getting-started-with-python), or follow a framework guide: [Django](/en/tutorials/api/django), [Flask](/en/tutorials/api/flask) or [FastAPI](/en/tutorials/api/fastapi).
3. [Deploy automatically from GitHub](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/) on every push.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.