diff --git a/manual/advanced/blender_directory_layout.rst b/manual/advanced/blender_directory_layout.rst index 966ffc58e..6b13106c4 100644 --- a/manual/advanced/blender_directory_layout.rst +++ b/manual/advanced/blender_directory_layout.rst @@ -4,93 +4,118 @@ Blender's Directory Layout ************************** -This page documents the different directories used by Blender -*(which can be helpful for troubleshooting)*. +This page documents the different directories used by Blender. -There are three different directories Blender may use, -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. +This can be helpful for troubleshooting, automation and customization. -Platform Dependent Paths -======================== - -Here are the default locations for each system: +User Directories +================ +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:: ./|BLENDER_VERSION|/ -:USER: - .. parsed-literal:: $HOME/.config/blender/|BLENDER_VERSION|/ -:SYSTEM: - .. parsed-literal:: /usr/share/blender/|BLENDER_VERSION|/ +.. parsed-literal:: $HOME/.config/blender/|BLENDER_VERSION|/ -.. note:: - - 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|/ +If the ``$XDG_CONFIG`` environment variable is set: +.. parsed-literal:: $XDG_CONFIG_HOME/blender/|BLENDER_VERSION|/ macOS ----- -:LOCAL: - .. 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|/ - +.. parsed-literal:: /Users/$USER/Library/Application Support/Blender/|BLENDER_VERSION|/ Windows ------- -:LOCAL: - .. 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|\\ +Download from blender.org: -.. note:: +.. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\ - For installations from the Window's Store, the ``USER`` and ``SYSTEM`` - directories are inside a special folder resembling: +Microsoft Store installation: - .. parsed-literal:: %ProgramFiles%\\WindowsApps\\BlenderFoundation.Blender\\Blender\\\ |BLENDER_VERSION|\\ +.. parsed-literal:: %ProgramFiles%\\WindowsApps\\BlenderFoundation.Blender\\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\\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. diff --git a/manual/advanced/command_line/arguments.rst b/manual/advanced/command_line/arguments.rst index f30d24f63..a8bf42905 100644 --- a/manual/advanced/command_line/arguments.rst +++ b/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. - (other ``BLENDER_USER_*`` variables override when set). +:BLENDER_USER_RESOURCES: Replace default directory of all user files. + 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. - (other ``BLENDER_SYSTEM_*`` variables override when set). -:BLENDER_SYSTEM_SCRIPTS: Directory for system wide scripts. -:BLENDER_SYSTEM_DATAFILES: Directory for system wide data files. -:BLENDER_SYSTEM_PYTHON: Directory for system Python libraries. +:BLENDER_SYSTEM_RESOURCES: Replace default directory of all bundled resource files. + Other ``BLENDER_SYSTEM_*`` variables override or add when set. +:BLENDER_SYSTEM_SCRIPTS: Directory to add more bundled scripts. +:BLENDER_SYSTEM_DATAFILES: Directory to replace bundled datafiles. +: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). diff --git a/manual/advanced/extensions/addons.rst b/manual/advanced/extensions/addons.rst index f10bf4a3b..2689ee468 100644 --- a/manual/advanced/extensions/addons.rst +++ b/manual/advanced/extensions/addons.rst @@ -72,6 +72,7 @@ Bundle with `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 diff --git a/manual/getting_started/about/introduction.rst b/manual/getting_started/about/introduction.rst index 6fb972f65..5c0efbdd1 100644 --- a/manual/getting_started/about/introduction.rst +++ b/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 `__ 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 `__. diff --git a/manual/getting_started/installing/linux.rst b/manual/getting_started/installing/linux.rst index 33ce1b8c9..f16cae222 100644 --- a/manual/getting_started/installing/linux.rst +++ b/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 `. + Install from Package Manager ============================ diff --git a/manual/getting_started/installing/macos.rst b/manual/getting_started/installing/macos.rst index 1ffeda2c4..f57317acd 100644 --- a/manual/getting_started/installing/macos.rst +++ b/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 keep all configuration files and installed add-ons inside the Blender application bundle, - create a folder named ``config`` in the :ref:`LOCAL directory `. - - .. parsed-literal:: ./Blender.app/Contents/Resources/|BLENDER_VERSION|/config/ +To make the installation and configuration fully self-contained, set up a +:ref:`Portable Installation `. Updating on macOS diff --git a/manual/getting_started/installing/windows.rst b/manual/getting_started/installing/windows.rst index 21558eadb..e23ef57f9 100644 --- a/manual/getting_started/installing/windows.rst +++ b/manual/getting_started/installing/windows.rst @@ -30,11 +30,8 @@ manually by clicking *Make Default* on the System tab of the :doc:`Preferences `. Alternatively, you can run ``blender -r`` from the :doc:`Command Line `. -.. tip:: How to Make a 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 ` - of the unzipped folder. +To make the installation and configuration fully self-contained, set up a +:ref:`Portable Installation `. Install from Microsoft Store