Core: Updates for portable installation and system path changes #104810

Merged
Brecht Van Lommel merged 1 commits from brecht/blender-manual:portable-system into blender-v4.2-release 2024-06-06 15:31:02 +02:00
7 changed files with 110 additions and 97 deletions

View File

@ -4,93 +4,118 @@
Blender's Directory Layout 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 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 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 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 Path Layout
@ -98,6 +123,9 @@ Path Layout
This is the path layout which is used within the directories described above. 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. Where ``./config/startup.blend`` could be ``~/.blender/|BLENDER_VERSION|/config/startup.blend`` for example.
``./autosave/ ...`` ``./autosave/ ...``
@ -200,16 +228,3 @@ The temporary directory is selected based on the following priority:
- User Preference (see :ref:`prefs-file-paths`). - User Preference (see :ref:`prefs-file-paths`).
- Environment variables (``TEMP`` on Windows, ``TMP`` & ``TMP_DIR`` on other platforms). - Environment variables (``TEMP`` on Windows, ``TMP`` & ``TMP_DIR`` on other platforms).
- The ``/tmp/`` directory. - 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.

View File

@ -484,18 +484,19 @@ Arguments are executed in the order they are given. eg:
Environment Variables 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_CONFIG: Directory for user configuration files.
:BLENDER_USER_SCRIPTS: Directory for user scripts. :BLENDER_USER_SCRIPTS: Directory for user scripts.
:BLENDER_USER_EXTENSIONS: Directory for user extensions. :BLENDER_USER_EXTENSIONS: Directory for user extensions.
:BLENDER_USER_DATAFILES: Directory for user data files (icons, translations, ..). :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. :OCIO: Path to override the OpenColorIO configuration file.
:TEMP: Store temporary files here (MS-Windows). :TEMP: Store temporary files here (MS-Windows).
:TMPDIR: Store temporary files here (UNIX Systems). :TMPDIR: Store temporary files here (UNIX Systems).

View File

@ -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 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: .. _bpy.ops.preferences.addon_install:
Legacy vs Extension Add-ons Legacy vs Extension Add-ons

View File

@ -45,7 +45,7 @@ Key Features
- It has a high-quality 3D architecture, enabling fast and efficient creation workflow. - 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>`__ - It boasts active community support. See `blender.org/community <https://www.blender.org/community>`__
for an extensive list of sites. 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/>`__. You can download the latest version of Blender `here <https://www.blender.org/download/>`__.

View File

@ -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. they will automatically open in Blender.
These settings are typically found in conjunction with the Window Manager settings. (Gnome or KDE.) 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 Install from Package Manager
============================ ============================

View File

@ -18,12 +18,8 @@ Then drag ``Blender.app`` into the Applications folder.
Depending on the Security and Privacy preferences of your Mac, Depending on the Security and Privacy preferences of your Mac,
macOS will request your approval before opening Blender for the first time. 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 Updating on macOS

View File

@ -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`` :doc:`Preferences </editors/preferences/system>`. Alternatively, you can run ``blender -r``
from the :doc:`Command Line </advanced/command_line/arguments>`. 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 Install from Microsoft Store