Deploy static view files

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 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 files deployment is affected by Magento modes as follows:

  • The default and developer mode: Magento generates them on demand, but the rest are cached in a file for speed of access.
  • The 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, see the Clean static files cache topic for details.

First steps

  1. Log in to the Magento server as, or switch to, a user who has permissions to write to the Magento file system. One way to do this is to switch to the Magento file system owner.

    If you use the bash shell, you can also use the following syntax to switch to the Magento file system owner and enter the command at the same time:

    su <Magento file system owner> -s /bin/bash -c <command> If the Magento file system owner does not allow logins you can do the following
    
    sudo -u <Magento file system owner>  <command>
    
  2. To run Magento commands from any directory, add <your Magento install dir>/bin to your system PATH.

    Because shells have differing syntax, consult a reference like unix.stackexchange.com.

    bash shell example for CentOS:

    export PATH=$PATH:/var/www/html/magento2/bin
    

You can also run the commands in the following ways:

  • cd <your Magento install dir>/bin and run them as ./magento <command name>
  • php <your Magento install dir>/bin/magento <command name>

<your Magento install dir> is a subdirectory of your web server's docroot. Need help locating the docroot? Click here.

In addition to the command arguments discussed here, see Common arguments.

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 [<list of languages>] [-t|--theme[="<theme>"]] [--exclude-theme[="<theme>"]] [-l|--language[="<language>"]] [--exclude-language[="<language>"]] [-a|--area[="<area>"]] [--exclude-area[="<area>"]] [-j|--jobs[="<number>"]]  [--no-javascript] [--no-css] [--no-less] [--no-images] [--no-fonts] [--no-html] [--no-misc] [--no-html-minify] [-d|--dry-run] 

The following table discusses the meanings of this command’s parameters and values.

Option Description Required?
<lang>

List of ISO-636 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

--language (-l)

Generate files only for the specified languages. The default, with no option specified, is to generate files for all ISO-636 language codes. You can specify the name of one language code at a time.

For example, --language en_US --language es_ES

No

--exclude-language

Generate files for the specified language codes. The default, with no option specified, is to exclude nothing. You can specify the name of one language code or a comma-separated list of language codes.

No

--theme <theme>

Themes for which to deploy static content.

For example, --theme Magento/blank --theme Magento/luma

No

--exclude-theme <theme>

Themes to exclude when deploying static content.

For example, --exclude-theme Magento/blank --theme Magento/luma

No

--area (-a)

Generate files only for the specified areas. The default, with no option specified, is to generate files for all areas. Valid values are adminhtml and frontend.

For example, --area adminhtml

No

--exclude-area

Do not generate files for the specified areas. The default, with no option specified, is to exclude nothing.

No

--jobs (-j)

Enable parallel processing using the specified number of jobs. The default is 4. To cause the task to run in one process (for example, if your system does not support process forking), use --jobs 1.

No

--no-javascript

Do not deploy JavaScript files

No

--no-css

Do not deploy CSS files.

No

--no-less

Do not deploy LESS files.

No

--no-images Do not deploy images.

No

--no-fonts

Do not deploy font files.

No

--no-html

Do not deploy HTML files.

No

--no-misc

Do not deploy other types of files (that is .md, .jbf, .csv, .json, .txt, .htc, or .swf files).

No

--no-html-minify

Do not minify HTML files.

No

--dry-run (-d)

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

No

  • If you specify values for both lang and --language, <lang> takes precedence.
  • The following parameters were added in version 2.1.1: --exclude-language, --theme <theme>, --exclude-theme <theme>, --area (-a), --exclude-area, --jobs (-j), --no-javascript, --no-css, --no-less, --no-images, --no-fonts, --no-html, --no-misc, --no-html-minify.

Deploy static view files without installing Magento

We regret that this information was added in error. You cannot yet deploy static view files without a connection to the Magento database. We expect this ability will be added in a future release. We apologize for any inconvenience this might have caused.

You should be able to compile code without a connection to the Magento database.

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.

Tip for developers customizing the static content deployment tool

When creating a custom implementation of the static content deployment tool, use only atomic file writing for files that should be available on the client. If you use non-atomic file writing, those files might be loaded on the client with partial content.

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