Create File

The Create File operation creates a new file or replaces a file. This operation is supported in version 2025-05-05 and later for File Shares with NFS protocol enabled. When you call Create File, you only initialize the file. To add content to a file, you call the Put Range operation. Beginning with version 2026-02-06, you can also create file with content up to 4MiB using Create File operation.

Protocol availability

Enabled file share protocol	Available
SMB
NFS

Request

The Create File request is constructed as follows. We recommend that you use HTTPS.

Replace the path components that are shown in the request URI with your own, as described in the following table:

For information about path-naming restrictions, see Name and reference shares, directories, files, and metadata.

URI parameters

You can specify the following additional parameters on the request URI:

Request headers

The required and optional request headers are described in the following tables:

Common request headers

SMB only request headers

NFS only request headers

Request body

None if Content-Length is zero. Required if Content-Length header is set to non zero. This is supported in version 2026-02-06 or later. The number of bytes specified in the request body and Content-Length header must match to perform the create file with data operation. The maximum number of bytes that can be specified in the request body is 4MiB.

Sample request

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile HTTP/1.1  
  
Request Headers:  
x-ms-version: 2020-02-10
x-ms-date: Mon, 27 Jan 2014 22:41:55 GMT  
Content-Type: text/plain; charset=UTF-8  
x-ms-content-length: 1024  
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=  

Sample request with Content-Length header

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile HTTP/1.1  
  
Request Headers:  
x-ms-version: 2026-02-06
x-ms-date: Mon, 27 Jan 2014 22:41:55 GMT  
Content-Type: text/plain; charset=UTF-8  
x-ms-content-length: 1024
Content-Length: 512
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=  

Response

The response includes an HTTP status code and a set of response headers.

Status code

A successful operation returns status code 201 (Created). For information about status codes, see Status and error codes.

Response headers

The response for this operation includes the headers in the following tables. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Common response headers

SMB only response headers

NFS only response headers

Response body

None.

Sample response

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
Date: Mon, 27 Jan 2014 23:00:12 GMT  
ETag: "0x8CB14C3E29B7E82"  
Last-Modified: Mon, 27 Jan 2014 23:00:06 GMT  
x-ms-version: 2014-02-14  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  

Authorization

Only the account owner can call this operation.

File system attributes

POSIX file permissions (mode)

POSIX file permissions can be specified either numerically in a 12-bit numeric octal format or in a symbolic "rwx" format. Examples:

• "0644" or "rw-r--r--": User (file owner) has read, write permission. Group has read permission. Others have read permission.
• "0755" or "rwxr-xr-x": User (file owner) has read, write, and execute permission. Group has read and execute permission. Others have read and execute permission.

Numeric octal format

The three lowest order octal numbers represent the permissions for owner/user, group, and others and are indicated using an octal number (0-7), formed using a bitwise combination of '4' (Read), '2' (Write), '1' (Execute). The highest order octal number (0-7) is used to indicate a combination of '4' (SetUID), '2' (SetGID), '1' (StickyBit) permissions.

Symbolic "rwx" format

Permissions for owner/user, group, and others are indicated using a combination of 'r' (Read), 'w' (Write), and 'x' (Execute) characters.

Remarks

To create a new file, first initialize it by calling Create File and specifying its maximum size, up to 4 TiB. When you're performing this operation, don't include content in the request body. After you've created the file, call Put Range to add content to the file or to modify it.

From version 2026-02-06 and later, you can create file with the data up to 4MiB by providing content in the request body. After you've created file with the data, call Put Range to append more data to the file or to modify it. The maximum size of the file created is up to 4 TiB.

You can change the size of the file by calling Set File Properties.

If the share or parent directory doesn't exist, then the operation fails with status code 412 (Precondition Failed).

To create the file, if the existing file has an active lease, the client must specify a valid lease ID on the request. If the client either doesn't specify a lease ID or specifies an invalid lease ID, Azure Files returns status code 412 (Precondition Failed). If the client specifies a lease ID but the file doesn't have an active lease, Azure Files returns status code 412 (Precondition Failed) in this instance also. If the client specifies a lease ID on a file that doesn't yet exist, Azure Files returns status code 412 (Precondition Failed) for requests that are made against version 2019-02-02 and later.

If an existing file with an active lease is overwritten by a Create File operation, the lease persists on the updated file until it's released.

Create File isn't supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot fails with status code 400 (InvalidQueryParameterValue).

See also

Operations on Files