manual/advanced/blender_directory_layout.rst

@@ -4,93 +4,118 @@
 Blender's Directory Layout
 **************************
 
-This page documents the different directories used by Blender
+This page documents the different directories used by Blender.
-*(which can be helpful for troubleshooting)*.
 
-There are three different directories Blender may use,
+This can be helpful for troubleshooting, automation and customization.
-their exact locations are platform dependent.
-
-:LOCAL:
-   Location of configuration and run-time data (for self-contained bundle).
-:USER:
-   Location of configuration files (typically in the user's home directory).
-:SYSTEM:
-   Location of run-time data for system wide installation (may be read-only).
-
-For system installations both **SYSTEM** and **USER** directories are needed.
-
-For locally extracted Blender distributions, the user configuration and run-time data are
-kept in the same subdirectory, allowing multiple Blender versions to run without conflict,
-ignoring the **USER** and **SYSTEM** files.
-This requires you to create a folder named ``config`` in the **LOCAL** directory.
 
 
-Platform Dependent Paths
+User Directories
-========================
+================
-
-Here are the default locations for each system:
 
+User directories store preferences, startup file, installed extensions,
+presets and more. By default these use the standard configuration folders
+for each operating system.
 
 Linux
 -----
 
-:LOCAL:
+.. parsed-literal:: $HOME/.config/blender/|BLENDER_VERSION|/
-   .. parsed-literal:: ./|BLENDER_VERSION|/
-:USER:
-   .. parsed-literal:: $HOME/.config/blender/|BLENDER_VERSION|/
-:SYSTEM:
-   .. parsed-literal:: /usr/share/blender/|BLENDER_VERSION|/
 
-.. note::
+If the ``$XDG_CONFIG`` environment variable is set:
-
-   The path |INSTALLDIR| is relative to the Blender executable and
-   is used for self-contained bundles distributed by official blender.org builds.
-
-.. |INSTALLDIR| replace:: ./|BLENDER_VERSION|/
-
-.. note::
-
-   The **USER** path will use ``$XDG_CONFIG_HOME`` if it is set:
-
-   .. parsed-literal:: $XDG_CONFIG_HOME/blender/|BLENDER_VERSION|/
 
+.. parsed-literal:: $XDG_CONFIG_HOME/blender/|BLENDER_VERSION|/
 
 macOS
 -----
 
-:LOCAL:
+.. parsed-literal:: /Users/$USER/Library/Application Support/Blender/|BLENDER_VERSION|/
-   .. parsed-literal:: ./|BLENDER_VERSION|/
-:USER:
-   .. parsed-literal:: /Users/$USER/Library/Application Support/Blender/|BLENDER_VERSION|/
-:SYSTEM:
-   .. parsed-literal:: /Library/Application Support/Blender/|BLENDER_VERSION|/
-
-.. note::
-
-   macOS stores the Blender binary in ``./Blender.app/Contents/MacOS/Blender``.
-   The local path to data and config is:
-
-   .. parsed-literal:: ./Blender.app/Contents/Resources/|BLENDER_VERSION|/
-
 
 Windows
 -------
 
-:LOCAL:
+Download from blender.org:
-   .. parsed-literal:: .\\\ |BLENDER_VERSION|\\
-:USER:
-   .. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
-:SYSTEM:
-   .. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
 
-.. note::
+.. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
 
-   For installations from the Window's Store, the ``USER`` and ``SYSTEM``
+Microsoft Store installation:
-   directories are inside a special folder resembling:
 
-   .. parsed-literal:: %ProgramFiles%\\WindowsApps\\BlenderFoundation.Blender<HASH>\\Blender\\\ |BLENDER_VERSION|\\
+.. parsed-literal:: %ProgramFiles%\\WindowsApps\\BlenderFoundation.Blender<HASH>\\Blender\\\ |BLENDER_VERSION|\\
 
-   Where "HASH" is a string specific to each installation.
+.. _portable-installation:
+
+Portable Installation
+---------------------
+
+When running Blender from a portable drive, it's possible to keep the configuration
+files on the same drive to take with you.
+
+To enable this, create a folder named ``portable`` at the following locations:
+
+* Windows: Next to the Blender executable, in the unzipped folder
+* Linux: Next to the Blender executable, in the unzipped folder
+* macOS: Inside the application bundle at ``Blender.app/Contents/Resources``
+
+This folder will then store preferences, startup file, installed extensions
+and presets.
+
+Environment Variables
+---------------------
+
+``BLENDER_USER`` :ref:`command-line-args-environment-variables` can be used to store
+some or all configuration files in other directories.
+
+This may be used for example when using a different configuration for a specific
+project, without affecting the regular user configuration.
+
+
+System Directories
+==================
+
+System directories store files that come bundled with Blender and
+are required for it to function. This includes scripts, presets, essential
+assets and more. 
+
+Linux
+-----
+
+Download from blender.org:
+
+.. parsed-literal:: ./|BLENDER_VERSION|/
+
+Linux distribution packages:
+
+.. parsed-literal:: /usr/share/blender/|BLENDER_VERSION|/
+
+macOS
+-----
+
+.. parsed-literal:: ./Blender.app/Contents/Resources/|BLENDER_VERSION|/
+
+Windows
+-------
+
+Zip file download from blender.org:
+
+.. parsed-literal:: ./|BLENDER_VERSION|/
+
+Installer download from blender.org:
+
+.. parsed-literal:: %ProgramFiles%\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
+
+Microsoft Store installation:
+
+.. parsed-literal:: %ProgramFiles%\\WindowsApps\\BlenderFoundation.Blender<HASH>\\Blender\\\ |BLENDER_VERSION|\\
+
+
+Environment Variables
+---------------------
+
+``BLENDER_SYSTEM`` :ref:`command-line-args-environment-variables`
+can be used to bundle additional scripts and extensions, that are not part of the
+regular Blender installation.
+
+This can be used for example to deploy Blender in an animation studio, with
+additional add-ons available to all users.
 
 
 Path Layout
@@ -98,6 +123,9 @@ Path Layout
 
 This is the path layout which is used within the directories described above.
 
+Configuration files are only stored in user directories, while scripts and data
+files can exist in both user and system directories.
+
 Where ``./config/startup.blend`` could be ``~/.blender/|BLENDER_VERSION|/config/startup.blend`` for example.
 
 ``./autosave/ ...``
@@ -200,16 +228,3 @@ The temporary directory is selected based on the following priority:
 - User Preference (see :ref:`prefs-file-paths`).
 - Environment variables (``TEMP`` on Windows, ``TMP`` & ``TMP_DIR`` on other platforms).
 - The ``/tmp/`` directory.
-
-
-Overriding Default Directories
-==============================
-
-It's possible to override the default **USER** and **SYSTEM** directories using environment variables.
-
-While this shouldn't be needed for typical usage, some specialized use cases may take advantage of this, such as:
-
-- Using a shared network drives for specific paths.
-- Isolating an instance from the default user files to prevent automated tasks from accessing user configuration.
-
-See :ref:`command-line-args-environment-variables` for details.

manual/advanced/command_line/arguments.rst

@@ -484,18 +484,19 @@ Arguments are executed in the order they are given. eg:
 Environment Variables
 =====================
 
-:BLENDER_USER_RESOURCES:  Top level directory for user files.
+:BLENDER_USER_RESOURCES:  Replace default directory of all user files.
-                         (other ``BLENDER_USER_*`` variables override when set).
+                          Other ``BLENDER_USER_*`` variables override when set.
 :BLENDER_USER_CONFIG:     Directory for user configuration files.
 :BLENDER_USER_SCRIPTS:    Directory for user scripts.
 :BLENDER_USER_EXTENSIONS: Directory for user extensions.
 :BLENDER_USER_DATAFILES:  Directory for user data files (icons, translations, ..).
 
-:BLENDER_SYSTEM_RESOURCES:  Top level directory for system files.
+:BLENDER_SYSTEM_RESOURCES:  Replace default directory of all bundled resource files.
-                           (other ``BLENDER_SYSTEM_*`` variables override when set).
+                            Other ``BLENDER_SYSTEM_*`` variables override or add when set.
-:BLENDER_SYSTEM_SCRIPTS:    Directory for system wide scripts.
+:BLENDER_SYSTEM_SCRIPTS:    Directory to add more bundled scripts.
-:BLENDER_SYSTEM_DATAFILES:  Directory for system wide data files.
+:BLENDER_SYSTEM_DATAFILES:  Directory to replace bundled datafiles.
-:BLENDER_SYSTEM_PYTHON:     Directory for system Python libraries.
+:BLENDER_SYSTEM_PYTHON:     Directory to replace bundled Python libraries.
+
 :OCIO:                      Path to override the OpenColorIO configuration file.
 :TEMP:                      Store temporary files here (MS-Windows).
 :TMPDIR:                    Store temporary files here (UNIX Systems).

manual/advanced/extensions/addons.rst

@@ -72,6 +72,7 @@ Bundle with `Vendorize <https://pypi.org/project/vendorize>`__
 
    This has the advantage of avoiding version conflicts although it requires some work to setup each package.
 
+.. This section is reference for legacy add-on installation.
 .. _bpy.ops.preferences.addon_install:
 
 Legacy vs Extension Add-ons

manual/getting_started/about/introduction.rst

@@ -45,7 +45,7 @@ Key Features
 - It has a high-quality 3D architecture, enabling fast and efficient creation workflow.
 - It boasts active community support. See `blender.org/community <https://www.blender.org/community>`__
   for an extensive list of sites.
-- It has a small executable, which is optionally portable.
+- It can be installed into and run from any directory without modifying the system.
 
 You can download the latest version of Blender `here <https://www.blender.org/download/>`__.
 

manual/getting_started/installing/linux.rst

@@ -23,6 +23,9 @@ You may also associate blend-files with Blender so that when selected from the f
 they will automatically open in Blender.
 These settings are typically found in conjunction with the Window Manager settings. (Gnome or KDE.)
 
+To make the installation and configuration fully self-contained, set up a
+:ref:`Portable Installation <portable-installation>`.
+
 
 Install from Package Manager
 ============================

manual/getting_started/installing/macos.rst

@@ -18,12 +18,8 @@ Then drag ``Blender.app`` into the Applications folder.
 Depending on the Security and Privacy preferences of your Mac,
 macOS will request your approval before opening Blender for the first time.
 
-.. tip:: How to Make a Portable Installation
+To make the installation and configuration fully self-contained, set up a
-
+:ref:`Portable Installation <portable-installation>`.
-   To keep all configuration files and installed add-ons inside the Blender application bundle,
-   create a folder named ``config`` in the :ref:`LOCAL directory <blender-directory-layout>`.
-
-   .. parsed-literal:: ./Blender.app/Contents/Resources/|BLENDER_VERSION|/config/
 
 
 Updating on macOS

manual/getting_started/installing/windows.rst

@@ -30,11 +30,8 @@ manually by clicking *Make Default* on the System tab of the
 :doc:`Preferences </editors/preferences/system>`. Alternatively, you can run ``blender -r``
 from the :doc:`Command Line </advanced/command_line/arguments>`.
 
-.. tip:: How to Make a Portable Installation
+To make the installation and configuration fully self-contained, set up a
-
+:ref:`Portable Installation <portable-installation>`.
-   To keep all configuration files and installed add-ons in the executable folder,
-   create a folder named ``config`` in the :ref:`LOCAL directory <blender-directory-layout>`
-   of the unzipped folder.
 
 
 Install from Microsoft Store