1. Home
2. Guides
3. Full-Site Delivery
4. Fastly VCL

Fastly allows you create your own Varnish Configuration Language (VCL) files with specialized configurations. By uploading custom VCL files, you can use custom VCL and Fastly VCL together at the same time. Any time you upload VCL files, you can preview the VCL prior to activating a new version of your service. Keep in mind that your custom VCL always takes precedence over VCL generated by Fastly.

For guidance on writing VCL code, including common use cases and best practices, check out our Writing VCL code guide.

Creating a custom VCL file

To create a custom VCL file, follow these steps. You'll use Fastly's VCL boilerplate when creating new files to prevent errors from duplicate definitions, conflicts, and version-specific metadata.

1. Log in to the Fastly control panel.

2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL.
5. Click Custom VCL.
6. Click Upload Custom VCL.
7. In the Name field, enter an appropriate name.
8. In the VCL editor, click Insert boilerplate code.
9. Edit the boilerplate as needed with your custom VCL. For help writing your VCL logic, check out our Writing VCL code guide.
10. Click Add. The custom VCL file appears in the list of VCL files on the Custom VCL tab. If this is your first custom VCL file, it will automatically be labeled as your main VCL file.

Editing a custom VCL file

To edit an existing VCL file, follow these instructions:

1. Log in to the Fastly control panel.

2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL.
5. Click Custom VCL.
6. From the list of custom VCL files, select the one you want to edit.
7. Click Edit.
8. (Optional) In the Name field, enter a new name for the custom VCL file.
9. In the VCL editor area, make the necessary code changes to your file. For help writing your VCL logic, check out our Writing VCL code guide.
10. Click Save to update the VCL file in the Fastly application.

11. Click Activate to deploy your configuration changes.

Downloading a VCL file

To download an existing VCL file, including your complete VCL, follow these instructions:

1. Log in to the Fastly control panel.

2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL.
5. Click Custom VCL.
6. Click the three dots to the right of the file name for the file you want to download.
7. Select Download from the menu that appears.

Uploading a custom VCL file

Follow these instructions to upload a custom VCL file:

1. Log in to the Fastly control panel.

2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL.
5. Click Custom VCL.
6. Click Upload custom VCL file.
7. In the Name field, enter the name of the VCL file. If you're using multiple VCL files, this name must match the name you use to reference the custom file in your main VCL. Our guidance on using multiple VCL files describes this in more detail.
8. Click Upload config file and select a file to upload.
9. Click Open. The VCL file appears with a confirmation message "Filename accepted."
10. Click Add.

11. Click Activate to deploy your configuration changes.

Using multiple custom VCL configuration files

To make your VCL configurations easier to maintain, you can split your VCL file into multiple files, each of which will be accessed by a main VCL file. This allows you to separate out chunks of logic (for example, logic that has a specific purpose or that might change frequently) into as many separate files as makes sense.

Setting up multiple VCL files

To use multiple custom VCL files, follow these steps:

1. Start by isolating a portion of VCL and placing it in a separate file. The name of the file doesn't matter, nor does the file extension. A foo.vcl file will work just as well as a bar.txt file.

2. Upload the file to include it in your Varnish configurations and give it a unique name when you fill out the Name field at the time of upload (for example, you could call it Included VCL). The uploaded file will appear in the Varnish Configurations area along with your main VCL file.

3. In the main VCL file, enter the name of the included VCL file on a separate line. For example, your Included VCL file would get added to the main VCL file in a single line like this:

   include "Included VCL";

4. Continue uploading VCL files and then including them in your main VCL using the syntax include "<VCL FILE>";, where <VCL FILE> exactly matches the name you entered in the Name field of your custom VCL.

5. Decide if you want to change which file serves as your main VCL file.

6. Click Activate to deploy your configuration changes.

Changing which file serves as your main VCL file

When you use multiple VCL files, you can change which one serves as the main VCL file by following these steps:

1. Log in to the Fastly control panel.

2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL.
5. Click Custom VCL.
6. Click the three dots to the right of the file name for the file you want to be your main VCL file.
7. Select Set as main config from the menu that appears.

8. Click Activate to deploy your configuration changes.

Deleting a custom VCL file

1. Log in to the Fastly control panel.

2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL.
5. Click Custom VCL.
6. Click the three dots to the right of the file name for the file you want to delete.
7. Select Delete from the menu that appears.
8. Confirm you want to delete the custom VCL file by clicking Delete.

Previewing VCL before activation

Follow these instructions to preview VCL prior to activating a service version:

1. Log in to the Fastly control panel.

2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. Click Show VCL. The VCL preview page appears.

Reviewing VCL errors

If there are syntax errors or other issues in your custom VCL, Fastly will identify them when you try to activate your service version. To review and fix VCL errors:

1. Log in to the Fastly control panel.

2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL.
5. Click the warning indicator above the VCL tabs. A list of errors, their descriptions, and a link to their locations in your VCL files appear.
6. Click the error you want to review. Your complete VCL file appears with the error line highlighted.
7. Fix the error with the appropriate edits. For help with common use cases, check out our guide to writing VCL code. Our VCL reference provides details about VCL syntax.

8. Click Activate to deploy your configuration changes.

Related content

• Writing VCL code
• VCL reference
• VCL API documentation