Deploy static view files

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

Run 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 presentation layer (from MVC).

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

Static view files 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 <magento_root>/pub/static, except for the .htaccess file. Do not delete this file.
  3. Run the static view files deployment tool <magento_root>/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:

1
bin/magento setup:static-content:deploy [<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] [-f|--force]

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 bin/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-639 language codes. You can specify the name of one language code at a time. Default value is all.

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. Default value is none.

No

--theme <theme>

Themes for which to deploy static content. Default value is all.

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

No

--exclude-theme <theme>

Themes to exclude when deploying static content. Default value is none.

For example, --exclude-theme Magento/blank

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. Default value is all.

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. Default value is none.

No

--jobs (-j)

Enable parallel processing using the specified number of jobs. The default is 0 (do not run in parallel processes). Default value is 0.

No

--symlink-locale

Create symlinks for the files of those locales, which are passed for deployment, but have no customizations.

No

--content-version=CONTENT-VERSION

Custom version of static content can be used if running deployment on multiple nodes to ensure that static content version is identical and caching works properly.

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

-s
  • -s quick
  • -s standard
  • -s compact
Define the deployment strategy. Use these options only if you have more than one locale.
  • Use the quick strategy to minimize deployment time. This is the default command option if not specified.
  • Use the standard strategy to deploy all static view files for all packages.
  • Use the compact strategy to conserve disk space on the server.

No

--force (-f)

Deploy files in any mode. (by default, the static content deployment tool can be run only in production mode. Use this option to run it in default or developer mode).

No

If you specify values for both <languages> and --language, <languages> takes precedence.

Examples

Following are some example commands.

Excluding a theme and HTML minification

The following command deploys static content for the US English (en_US) language, excludes the Luma theme provided with Magento, and does not minify HTML files.

1
bin/magento setup:static-content:deploy en_US --exclude-theme Magento/luma --no-html-minify

Sample output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Requested languages: en_US
Requested areas: frontend, adminhtml
Requested themes: Magento/blank, Magento/backend
=== frontend -> Magento/blank -> en_US ===
=== adminhtml -> Magento/backend -> en_US ===
...........................................................
... more ...
Successful: 2055 files; errors: 0
---

New version of deployed files: 1466710645
............
Successful: 1993 files; errors: 0
---

Generating static view files for one theme and one area

The following command generates static view files for all languages, the frontend area only, the Magento Luma theme only, without generating fonts:

1
bin/magento setup:static-content:deploy --area frontend --no-fonts --theme Magento/luma

Sample output:

1
2
3
4
5
6
7
8
9
10
11
Requested languages: en_US
Requested areas: frontend
Requested themes: Magento/luma
=== frontend -> Magento/luma -> en_US ===
...........................................................
... more ...
........................................................................
Successful: 2092 files; errors: 0
---

New version of deployed files: 1466711110

Deploy static view files without installing Magento

You might want to run the deployment process in a separate, non-production, environment, to avoid any build processes on sensitive production machines.

To do this, take the following steps:

  1. Run bin/magento app:config:dump to export the configuration from your production system.
  2. Copy the exported files to the non-production code base.
  3. Run bin/magento setup:static-content:deploy.

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:

1
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 <magento_root>/pub/static directory, except for the .htaccess file. Do not delete this file.
  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.