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

# Como criar um arquivo pyproject.toml

> Crie o pyproject.toml de uma aplicação Python: declare metadados do projeto, dependências fixadas e um sistema de build para a Square Cloud instalar com pip.

O arquivo `pyproject.toml` é uma forma moderna de especificar todos os requisitos do sistema de build e as dependências do seu projeto em um único arquivo. Este guia mostra como criar, configurar e usar o `pyproject.toml` para garantir consistência entre os ambientes de desenvolvimento e produção.

## O que é um arquivo pyproject.toml?

Um `pyproject.toml` lista dependências, o sistema de build e outros metadados do seu projeto Python. Isso permite:

* Permitir que você e sua equipe mantenham ambientes idênticos
* Fazer com que novos colaboradores reproduzam o ambiente exatamente
* Configurar dependências de desenvolvimento e produção separadamente

***

<Steps>
  <Step title="Criar o arquivo pyproject.toml">
    Primeiro, crie um arquivo chamado `pyproject.toml` na raiz do seu projeto.
  </Step>

  <Step title="Defina os detalhes do seu projeto">
    No arquivo `pyproject.toml`, comece definindo os metadados do projeto. Vamos definir o nome do projeto, versão, descrição e outras informações relevantes.\
    O nome do projeto deve conter letras ASCII, dígitos, underscores "\_", hífens "-" e pontos ".". Não deve começar ou terminar com underscore, hífen ou ponto. Por exemplo:

    ```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="Listar dependências do projeto">
    Em seguida, vamos listar as dependências necessárias para o projeto. Podemos especificar dependências de produção e de desenvolvimento. As dependências de produção são listadas na seção `dependencies`, enquanto as dependências de desenvolvimento podem ser listadas em `optional-dependencies` com um nome de grupo específico (por exemplo, `dev`).\
    Você pode especificar versões para suas dependências usando operadores de comparação como `==`, `>=`, `<`... No exemplo abaixo, cada dependência está fixada em uma versão exata com `==`. É recomendado especificar versões exatas para garantir reprodutibilidade e evitar que atualizações incompatíveis quebrem o ambiente em produção.

    ```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="Configurar o sistema de build">
    Por fim, precisamos especificar os requisitos do sistema de build. Isso é necessário para que ferramentas como o pip saibam como construir e instalar seu projeto. Usaremos `setuptools` como backend de build, que é uma escolha comum, mas você pode escolher outros como o `poetry`.
    A linha `py-modules = []` em `[tool.setuptools]` informa ao setuptools que não há nenhum módulo para empacotar, então o `pip install .` apenas instala as dependências. Sem ela, uma aplicação com várias pastas de nível superior (por exemplo `cogs/` e `utils/`) falha com `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>

***

## Instalar dependências com pip

Para instalar as dependências listadas no `pyproject.toml`, você pode usar o `pip` ou outras ferramentas que suportem `pyproject.toml`. Isso permite trabalhar no projeto com as dependências instaladas.

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

Esse comando irá ler o `pyproject.toml`, instalar as dependências listadas em `dependencies` e configurar seu projeto para desenvolvimento. Também é o que a Square Cloud executa quando o seu upload tem um `pyproject.toml` e nenhum `requirements.txt`. Se quiser instalar também as dependências de desenvolvimento, use:

```bash theme={"system"}
pip install .[dev]
```

Isso instalará dependências de produção e de desenvolvimento, permitindo que você trabalhe no projeto com todas as ferramentas necessárias.

## Boas práticas e dicas

* **Mantenha atualizado**: Revise e atualize o `pyproject.toml` regularmente conforme adicionar novas dependências
* **Use versões exatas**: Prefira `==` em vez de `>`, `>=` ou não especificar versão para evitar surpresas em produção
* **Versionamento**: Faça commit do `pyproject.toml` no Git para rastrear mudanças de dependências e versões
* **Ambiente isolado**: Mantenha um ambiente virtual por projeto para evitar conflitos globais
* **Teste localmente**: Antes de realizar deploy, teste o arquivo com `pip install .` em um ambiente novo

***

## Próximos passos

Com seu `pyproject.toml` configurado:

1. Faça commit dele no seu repositório Git.
2. Hospede o seu projeto com o [guia do runtime Python](/pt-br/articles/getting-started-with-python), ou siga um guia de framework: [Django](/pt-br/tutorials/api/django), [Flask](/pt-br/tutorials/api/flask) ou [FastAPI](/pt-br/tutorials/api/fastapi).
3. [Faça deploy automático a partir do GitHub](https://help.squarecloud.app/pt-br/article/como-integrar-seu-repositorio-do-github-e-fazer-deploy-automatico-1nk6gr9/) a cada push.


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