---
title: "“Upload” de arquivos"
version: 1.9
locale: pt-br
source: https://docs.djangoproject.com/pt-br/1.9/topics/http/file-uploads/
canonical: https://djangodocs.dev/pt-br/1.9/topics/http/file-uploads/
---
# “Upload” de arquivos

Quando o Django lida com o upload de arquivos, o arquivo de dados termina sendo colocado em [`request.FILES`](/pt-br/1.9/ref/request-response/#django.http.HttpRequest.FILES) (para mais sobre o objeto `request` veja a documentação sobre [objetos de requisição e resposta](/pt-br/1.9/ref/request-response/)). Este documento explica como arquivos são armazenados no disco ou na memória, e como personalizar o comportamento padrão.

> **Warning**
>
> Existem riscos de segurança se você estiver aceitando o upload de conteúdo de usuários não confiáveis! Veja o tópico do guia de segurança em [User-uploaded content](/pt-br/1.9/topics/security/#user-uploaded-content-security) para detalhes.

## Básico sobre upload de arquivos

Consider a simple form containing a [`FileField`](/pt-br/1.9/ref/forms/fields/#django.forms.FileField):

*forms.py*

```
from django import forms

class UploadFileForm(forms.Form):
    title = forms.CharField(max_length=50)
    file = forms.FileField()
```

Uma “view” que lida com este formulário irá receber o arquivo em [`request.FILES`](/pt-br/1.9/ref/request-response/#django.http.HttpRequest.FILES), o qual é um dicionário contendo uma chave para cada [`FileField`](/pt-br/1.9/ref/forms/fields/#django.forms.FileField) (ou [`ImageField`](/pt-br/1.9/ref/forms/fields/#django.forms.ImageField), ou outra subclasse de [`FileField`](/pt-br/1.9/ref/forms/fields/#django.forms.FileField)) no formulário. Tal que os dados vindos do formulário acima devem estar acessíveis como `request.FILES['file']`.

Note que [`request.FILES`](/pt-br/1.9/ref/request-response/#django.http.HttpRequest.FILES) somente terá dados se o métodos de requisição for `POST` e o `<form>` que postou a requisição tem o atributo `enctype="multipart/form-data"`. Do contrário, o `request.FILES` estará vazio.

Most of the time, you’ll simply pass the file data from `request` into the
form as described in [Binding uploaded files to a form](/pt-br/1.9/ref/forms/api/#binding-uploaded-files). This would look
something like:

*views.py*

```
from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import UploadFileForm

# Imaginary function to handle an uploaded file.
from somewhere import handle_uploaded_file

def upload_file(request):
    if request.method == 'POST':
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            handle_uploaded_file(request.FILES['file'])
            return HttpResponseRedirect('/success/url/')
    else:
        form = UploadFileForm()
    return render(request, 'upload.html', {'form': form})
```

Note que temos que passar [`request.FILES`](/pt-br/1.9/ref/request-response/#django.http.HttpRequest.FILES) para o construtor do “form”; é assim que os dados do arquivo entra no form.

Aqui uma maneira comum que você talvez lide com o “upload” de arquivo:

```
def handle_uploaded_file(f):
    with open('some/file/name.txt', 'wb+') as destination:
        for chunk in f.chunks():
            destination.write(chunk)
```

Fazendo “loops” sobre `UploadedFile.chunks()` ao invés de usar o `read()` garante que grandes arquivos não vão forçar a memória do seu sistema.

Existem alguns outros métodos e atributos disponíveis nos objetos `UploadedFile`; veja a [`UploadedFile`](/pt-br/1.9/ref/files/uploads/#django.core.files.uploadedfile.UploadedFile) para uma completa referência.

### Lindando com o “upload” de arquivos com um modelo.

Se você está usando um arquivo em uma [`Model`](/pt-br/1.9/ref/models/instances/#django.db.models.Model) com uma [`FileField`](/pt-br/1.9/ref/models/fields/#django.db.models.FileField), usando uma [`ModelForm`](/pt-br/1.9/topics/forms/modelforms/#django.forms.ModelForm) faz este processo bem mais fácil. O objeto arquivo será salvo em um local especificado pelo argumento [`upload_to`](/pt-br/1.9/ref/models/fields/#django.db.models.FileField.upload_to) do [`FileField`](/pt-br/1.9/ref/models/fields/#django.db.models.FileField) correspondente quando chamar `form.save()`:

```
from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import ModelFormWithFileField

def upload_file(request):
    if request.method == 'POST':
        form = ModelFormWithFileField(request.POST, request.FILES)
        if form.is_valid():
            # file is saved
            form.save()
            return HttpResponseRedirect('/success/url/')
    else:
        form = ModelFormWithFileField()
    return render(request, 'upload.html', {'form': form})
```

If you are constructing an object manually, you can simply assign the file
object from [`request.FILES`](/pt-br/1.9/ref/request-response/#django.http.HttpRequest.FILES) to the file
field in the model:

```
from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import UploadFileForm
from .models import ModelWithFileField

def upload_file(request):
    if request.method == 'POST':
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            instance = ModelWithFileField(file_field=request.FILES['file'])
            instance.save()
            return HttpResponseRedirect('/success/url/')
    else:
        form = UploadFileForm()
    return render(request, 'upload.html', {'form': form})
```

### Uploading multiple files

If you want to upload multiple files using one form field, set the `multiple`
HTML attribute of field’s widget:

*forms.py*

```
from django import forms

class FileFieldForm(forms.Form):
    file_field = forms.FileField(widget=forms.ClearableFileInput(attrs={'multiple': True}))
```

Then override the `post` method of your
[`FormView`](/pt-br/1.9/ref/class-based-views/generic-editing/#django.views.generic.edit.FormView) subclass to handle multiple file
uploads:

*views.py*

```
from django.views.generic.edit import FormView
from .forms import FileFieldForm

class FileFieldView(FormView):
    form_class = FileFieldForm
    template_name = 'upload.html'  # Replace with your template.
    success_url = '...'  # Replace with your URL or reverse().

    def post(self, request, *args, **kwargs):
        form_class = self.get_form_class()
        form = self.get_form(form_class)
        files = request.FILES.getlist('file_field')
        if form.is_valid():
            for f in files:
                ...  # Do something with each file.
            return self.form_valid(form)
        else:
            return self.form_invalid(form)
```

## Upload Handlers

When a user uploads a file, Django passes off the file data to an *upload
handler* – a small class that handles file data as it gets uploaded. Upload
handlers are initially defined in the [`FILE_UPLOAD_HANDLERS`](/pt-br/1.9/ref/settings/#std-setting-FILE_UPLOAD_HANDLERS) setting,
which defaults to:

```
["django.core.files.uploadhandler.MemoryFileUploadHandler",
 "django.core.files.uploadhandler.TemporaryFileUploadHandler"]
```

Together [`MemoryFileUploadHandler`](/pt-br/1.9/ref/files/uploads/#django.core.files.uploadhandler.MemoryFileUploadHandler) and
[`TemporaryFileUploadHandler`](/pt-br/1.9/ref/files/uploads/#django.core.files.uploadhandler.TemporaryFileUploadHandler) provide Django’s default file upload
behavior of reading small files into memory and large ones onto disk.

You can write custom handlers that customize how Django handles files. You
could, for example, use custom handlers to enforce user-level quotas, compress
data on the fly, render progress bars, and even send data to another storage
location directly without storing it locally. See [Writing custom upload handlers](/pt-br/1.9/ref/files/uploads/#custom-upload-handlers)
for details on how you can customize or completely replace upload behavior.

### Where uploaded data is stored

Before you save uploaded files, the data needs to be stored somewhere.

By default, if an uploaded file is smaller than 2.5 megabytes, Django will hold
the entire contents of the upload in memory. This means that saving the file
involves only a read from memory and a write to disk and thus is very fast.

However, if an uploaded file is too large, Django will write the uploaded file
to a temporary file stored in your system’s temporary directory. On a Unix-like
platform this means you can expect Django to generate a file called something
like `/tmp/tmpzfp6I6.upload`. If an upload is large enough, you can watch this
file grow in size as Django streams the data onto disk.

These specifics – 2.5 megabytes; `/tmp`; etc. – are simply “reasonable
defaults” which can be customized as described in the next section.

### Changing upload handler behavior

There are a few settings which control Django’s file upload behavior. See
[File Upload Settings](/pt-br/1.9/ref/settings/#file-upload-settings) for details.

### Modifying upload handlers on the fly

Sometimes particular views require different upload behavior. In these cases,
you can override upload handlers on a per-request basis by modifying
`request.upload_handlers`. By default, this list will contain the upload
handlers given by [`FILE_UPLOAD_HANDLERS`](/pt-br/1.9/ref/settings/#std-setting-FILE_UPLOAD_HANDLERS), but you can modify the list
as you would any other list.

For instance, suppose you’ve written a `ProgressBarUploadHandler` that
provides feedback on upload progress to some sort of AJAX widget. You’d add this
handler to your upload handlers like this:

```
request.upload_handlers.insert(0, ProgressBarUploadHandler(request))
```

You’d probably want to use `list.insert()` in this case (instead of
`append()`) because a progress bar handler would need to run *before* any
other handlers. Remember, the upload handlers are processed in order.

If you want to replace the upload handlers completely, you can just assign a new
list:

```
request.upload_handlers = [ProgressBarUploadHandler(request)]
```

> **Note**
>
> You can only modify upload handlers *before* accessing
> `request.POST` or `request.FILES` – it doesn’t make sense to
> change upload handlers after upload handling has already
> started. If you try to modify `request.upload_handlers` after
> reading from `request.POST` or `request.FILES` Django will
> throw an error.
>
> Thus, you should always modify uploading handlers as early in your view as
> possible.
>
> Also, `request.POST` is accessed by
> [`CsrfViewMiddleware`](/pt-br/1.9/ref/middleware/#django.middleware.csrf.CsrfViewMiddleware) which is enabled by
> default. This means you will need to use
> [`csrf_exempt()`](/pt-br/1.9/ref/csrf/#django.views.decorators.csrf.csrf_exempt) on your view to allow you
> to change the upload handlers.  You will then need to use
> [`csrf_protect()`](/pt-br/1.9/ref/csrf/#django.views.decorators.csrf.csrf_protect) on the function that
> actually processes the request.  Note that this means that the handlers may
> start receiving the file upload before the CSRF checks have been done.
> Example code:
>
> ```
> from django.views.decorators.csrf import csrf_exempt, csrf_protect
>
> @csrf_exempt
> def upload_file_view(request):
>     request.upload_handlers.insert(0, ProgressBarUploadHandler(request))
>     return _upload_file_view(request)
>
> @csrf_protect
> def _upload_file_view(request):
>     ... # Process request
> ```