Deploy static view files

In addition to the command arguments described in this topic, see Common arguments.

You should be running all Magento CLI commands as the Magento file system owner.

Overview of static view files deployment

The static view files deployment command enables you to write static files to the Magento file system when the Magento software is set for production mode.

The term static view file refers to the following:

  • “Static” means it can be cached for a site (that is, the file is not dynamically generated). Examples include images and CSS generated from LESS.
  • “View” refers to the presentation layer (from MVC).

Static view files are located in the <your Magento install dir>/pub/static directory, and some are cached in the <your Magento install dir>/var/view_preprocessed directory as well.

Static view file deployment is affected by Magento modes as follows:

  • Default and developer modes: Magento generates them on demand, but the rest are cached in a file for speed of access.
  • Production mode: Static files are not generated or cached.

You must write static view files to the Magento file system manually using the command discussed in this topic; after that, you can restrict permissions to limit your vulnerabilities and to prevent accidental or malicious overwriting of files.

Developer mode only: When you install or enable a new module, it might load new JavaScript, CSS, layouts, and so on. To avoid issues with static files, you must clean the old files to make sure you get all the changes for the new module.

You can clean generated static view files in several ways. Refer to Clean static files cache topic for details for more information.

Deploy static view files

To deploy static view files:

  1. Log in to the Magento server as, or switch to, the Magento file system owner.
  2. Delete the contents of <your Magento install dir>/pub/static.

  3. Run the static view files deployment tool <your Magento install dir>/bin/magento setup:static-content:deploy.

    If you enable static view file merging in the Magento Admin, the pub/static directory system must be writable.

Command options:

magento setup:static-content:deploy <lang> ... <lang> [--dry-run]

The following table explains this command’s parameters and values.

Option Description Required?
<languages>

Space-separated list of ISO-639 language codes for which to output static view files. (Default is en_US.)

You can find the list by running magento info:language:list.

No
--dry-run

Include to view the files output by the tool without outputting anything.

No

For example, to deploy static view files for the pt_BR language:

magento --ansi setup:static-content:deploy pt_BR

The following are some sample messages that display to indicate successful deployment:

Requested languages: pt_BR
=== frontend -> Magento/luma -> pt_BR ===
... progress indicator ...
Successful: 1613 files; errors: 0

=== frontend -> Magento/blank -> pt_BR ===
... progress indicator ...
Successful: 1620 files; errors: 0

=== adminhtml -> Magento/backend -> pt_BR ===
... progress indicator ...
Successful: 1626 files; errors: 0

=== Minify templates ===
... progress indicator ...
Successful: 858 files modified
---
New version of deployed files: 1430773903

Troubleshooting the static view files deployment tool

Install the Magento software first; otherwise, you cannot run the static view files deployment tool.

Symptom: The following error is displayed when you run the static view files deployment tool:

ERROR: You need to install the Magento application before running this utility.

Solution:

Use the following steps:

  1. Install the Magento software in any of the following ways:

  2. Log in to the Magento server as, or switch to, the Magento file system owner.
  3. Delete the contents of <your Magento install dir>/pub/static directory.

  4. Run the static view files deployment tool.

Tips for developers customizing the static content deployment tool

When creating a custom implementation of the static content deployment tool, do not use non atomic writing to files that should be available on the client side. Otherwise, those files might be loaded on the client side with partial content.

One of the options for making it atomic, is writing to files stored in a temporary directory and copying or moving them to the destination directory (from where they are actually loaded to client side) once writing is over. For details about writing to files see http://php.net/manual/en/function.fwrite.php.

Please note, that the default Magento implementation of \Magento\Framework\Filesystem\Directory\WriteInterface::writeFile uses non-atomic write to file.