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
Showing only changes of commit 834e0f925c - Show all commits

View File

@ -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|/
.. 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:
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|/
Windows
-------
:LOCAL:
.. parsed-literal:: .\\\ |BLENDER_VERSION|\\
:USER:
.. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
:SYSTEM:
Download from blender.org:
.. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
.. note::
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<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.

View File

@ -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).

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 section is reference for legacy add-on installation.
.. _bpy.ops.preferences.addon_install:
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 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/>`__.

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.
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
============================

View File

@ -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 <blender-directory-layout>`.
.. parsed-literal:: ./Blender.app/Contents/Resources/|BLENDER_VERSION|/config/
To make the installation and configuration fully self-contained, set up a
:ref:`Portable Installation <portable-installation>`.
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``
from the :doc:`Command Line </advanced/command_line/arguments>`.
.. 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 <blender-directory-layout>`
of the unzipped folder.
To make the installation and configuration fully self-contained, set up a
:ref:`Portable Installation <portable-installation>`.
Install from Microsoft Store