---
title: "Configurações do Django"
version: 5.1
locale: pt-br
source: https://docs.djangoproject.com/pt-br/5.1/topics/settings/
canonical: https://djangodocs.dev/pt-br/5.1/topics/settings/
---
# Configurações do Django

Um arquivo de definições do Django contém todas as configurações da sua instalação do Django. Este documento explica como as configurações trabalham e quais definições estão disponíveis.

## O básico

Um arquivo de definições é somente um módulo Python com variáveis de módulo.

Aqui alguns exemplos de definições:

```
ALLOWED_HOSTS = ["www.example.com"]
DEBUG = False
DEFAULT_FROM_EMAIL = "webmaster@example.com"
```

> **Note**
>
> Se você definie o [`DEBUG`](/pt-br/5.1/ref/settings/#std-setting-DEBUG) para `False`, você também precisa definir a definição de [`ALLOWED_HOSTS`](/pt-br/5.1/ref/settings/#std-setting-ALLOWED_HOSTS).

Como o arquivo de definições é um módulo Python, o seguinte se aplica:

- Ele não permite erros de sintaxe Python.
- É possível assinalar definições dinamicamente usando sintaxe Python normalmente. Por exemplo:

  ```
  MY_SETTING = [str(i) for i in range(30)]
  ```
- Pode importar valores de outros arquivos de definições.

## Designando as definições

#### `DJANGO_SETTINGS_MODULE`

When you use Django, you have to tell it which settings you’re using. Do this
by using an environment variable, [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE).

The value of [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) should be in Python path syntax,
e.g. `mysite.settings`. Note that the settings module should be on the
Python [`sys.path`](https://docs.python.org/3/library/sys.html#sys.path).

### A ferramenta `django-admin`

Quando usar [django-admin](/pt-br/5.1/ref/django-admin/), você pode definir a variável de ambiente uam vez, ou passar explicitamente no módulo de definições cada vez que você rodar a ferramenta.

Example (Unix Bash shell):

```shell
export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver
```

Example (Windows shell):

```doscon
set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver
```

Use the `--settings` command-line argument to specify the settings manually:

```shell
django-admin runserver --settings=mysite.settings
```

### No servidor (`mod_wsgi`)

No seu ambiente do servidor de produção , você precisará dizer à sua aplicação WSGI qual arquivo de definições utilizar. Faça isso com `os.environ`:

```
import os

os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings"
```

Leia a [documentação do Django mod\_wsgi](/pt-br/5.1/howto/deployment/wsgi/modwsgi/) para mais informações e outros elementos comuns para uma aplicação WSGI Django.

## Definições padrão

A Django settings file doesn’t have to define any settings if it doesn’t need
to. Each setting has a sensible default value. These defaults live in the
module [django/conf/global\_settings.py](https://github.com/django/django/blob/stable/5.1.x/django/conf/global_settings.py).

Aqui está o algoritmo que o Django usa enquanto compila as definições:

- Carrega as definições do `global_settings.py`.
- Carrega as definições do arquivo de definições especificado, sobrescrevendo as definições globais quando necessário.

Note que o arquivo de definições *não* deve importar o `global_settings`, porque isso é redundante.

### Vendo quais definições você alterou

The command `python manage.py diffsettings` displays differences between the
current settings file and Django’s default settings.

Para mais detalhes, veja a documentação [`diffsettings`](/pt-br/5.1/ref/django-admin/#django-admin-diffsettings).

## Usando as definições em código Python

Nas suas apps Django, use as definições através da importação do objeto `django.conf.settings`. Exemplo:

```
from django.conf import settings

if settings.DEBUG:
    # Do something
    ...
```

Note que o `django.conf.settings` não é um módulo – é um objeto. Então não é possível importar definições individuais.

```
from django.conf.settings import DEBUG  # This won't work.
```

Também note que seu código *não* deve importar nem o `global_settings` nem seu próprio arquivo de definições. O `django.conf.settings` torna o conceito das definições padrão abstrato bem como as definições específicas do site; ele apresenta uma única interface. Ele também desacopla o código que usa as definições da localização das suas definições.

## Alterando as definições em tempo de execução

Você não deve alterar as definições dentro de sua aplicação durante a execução. Por exemplo, não faça isso em uma “view”:

```
from django.conf import settings

settings.DEBUG = True  # Don't do this!
```

O único local onde você deve assinalar a definições é em um arquivo de definições.

## Segurança

Because a settings file contains sensitive information, such as the database
password, you should make every attempt to limit access to it. For example,
change its file permissions so that only you and your web server’s user can
read it. This is especially important in a shared-hosting environment.

## Configurações disponíveis.

Para uma lista completa de configurações disponíveis, veja a [referência de configurações](/pt-br/5.1/ref/settings/).

## Criando suas próprias configurações

There’s nothing stopping you from creating your own settings, for your own
Django apps, but follow these guidelines:

- Nomes de definições devem estar em maiúsculo.
- Não reinvente uma configuração já existente.

Para definições que são sequências, mesmo o Django usa listas, mas isso é apenas uma convenção.

## Using settings without setting [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE)

In some cases, you might want to bypass the [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE)
environment variable. For example, if you’re using the template system by
itself, you likely don’t want to have to set up an environment variable
pointing to a settings module.

Nestes casos, você pode configurar manualmente as definições. Faça isso através da chamada:

#### `django.conf.settings.configure(default_settings, **settings)`

Exemplo

```
from django.conf import settings

settings.configure(DEBUG=True)
```

Passe ao `configure()` quantos argumentos nomeados você quiser, com cada argumento representando uma configuração e seu valor. Cada nome de argumento deve ser todo em maiúsculo, com o mesmo nome da configuração descrita acima. Se uma definição em particular não for passada para o `configure()` e e for necessária em algum ponto a diante, o Django irá usar o valor padrão para aquela configuração.

Configurando o Django desta maneira é sobretudo necessário – e, realmente, recomendado quando você está usando uma parte do framework dentro de uma aplicação maior.

Consequentemente, quando configurado através do `settings.configure()`, o Django não irá fazer qualquer modificação nas variáveis de ambiente do processo (veja a documentação do [`TIME_ZONE`](/pt-br/5.1/ref/settings/#std-setting-TIME_ZONE) para o porque disso não ocorrer normalmente). Ele assume que você já está com todo o controle do seu ambiente nestes casos.

### Definições padrão personalizadas

Se você quer que os valores padrão venham de algum outro lugar que não o `django.conf.global_settings`, você pode passar em um módulo ou classe que forneça as definições padrão como o argumento `default_settings` (ou como o primeiro argumento opcional) na chamada do `configure()`.

Neste exemplo, definições padrão são pegas do `myapp_defaults`, e a definição de [`DEBUG`](/pt-br/5.1/ref/settings/#std-setting-DEBUG) é definida como `True`, apesar de seu valor em `myapp_defaults`:

```
from django.conf import settings
from myapp import myapp_defaults

settings.configure(default_settings=myapp_defaults, DEBUG=True)
```

O exemplo seguinte, o qual usa `myapp_defaults` como um argumento posicional, é equivalente:

```
settings.configure(myapp_defaults, DEBUG=True)
```

Normally, you will not need to override the defaults in this fashion. The
Django defaults are sufficiently tame that you can safely use them. Be aware
that if you do pass in a new default module, it entirely *replaces* the Django
defaults, so you must specify a value for every possible setting that might be
used in the code you are importing. Check in
`django.conf.settings.global_settings` for the full list.

### Either `configure()` or [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) is required

If you’re not setting the [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) environment
variable, you *must* call `configure()` at some point before using any code
that reads settings.

If you don’t set [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) and don’t call
`configure()`, Django will raise an `ImportError` exception the first time
a setting is accessed.

If you set [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE), access settings values somehow,
*then* call `configure()`, Django will raise a `RuntimeError` indicating
that settings have already been configured. There is a property for this
purpose:

#### `django.conf.settings.configured`

Por exemplo:

```
from django.conf import settings

if not settings.configured:
    settings.configure(myapp_defaults, DEBUG=True)
```

E mais, é um erro chamar o `configure()` mais de uma vez, ou chamar o `configure()` depois que qualquer definição tenha sido acessada.

It boils down to this: Use exactly one of either `configure()` or
[`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE). Not both, and not neither.

### É mandatório chamar o `django.setup()` para o usar o Django de modo “standalone”

Se você está usando componentes do Django de modo “standalone” – por exemplo, escreveu um script Python o qual carrega alguns templates Django e os renderiza, ou usa o ORM para ler alguns dados – existe mais um passo que é necessário além de configurar as definições.

Depois de definir ou o [`DJANGO_SETTINGS_MODULE`](#envvar-DJANGO_SETTINGS_MODULE) ou chamado `configure()`, precisará chamar [`django.setup()`](/pt-br/5.1/ref/applications/#django.setup)  para carregar suas definições e popular o registro da aplicação Django. Por exemplo:

```
import django
from django.conf import settings
from myapp import myapp_defaults

settings.configure(default_settings=myapp_defaults, DEBUG=True)
django.setup()

# Now this script or any imported module can use any part of Django it needs.
from myapp import models
```

Note that calling `django.setup()` is only necessary if your code is truly
standalone. When invoked by your web server, or through [django-admin](/pt-br/5.1/ref/django-admin/), Django will handle this for you.

> **django.setup() deve ser chamado uma única vez.**
>
> Portanto, evite colocar lógica de aplicação reutilizável em scripts “standalone” de modo que tenha que importar o script em algum lugar da aplicação. Se você não puder evitar isso, coloque a chamada do  `django.setup()` dentro de um bloco `if`:
>
> ```
> if __name__ == "__main__":
>     import django
>
>     django.setup()
> ```

> **See also**
>
> **[A referência sobre configurações](/pt-br/5.1/ref/settings/)**
>
>   Contém uma lista completa das configurações do “core” e das aplicações do “contrib”.