Core: Updates for portable installation and system path changes #104810
@ -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:: ./|BLENDER_VERSION|/
|
|
||||||
:USER:
|
|
||||||
.. parsed-literal:: $HOME/.config/blender/|BLENDER_VERSION|/
|
.. 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:: ./|BLENDER_VERSION|/
|
|
||||||
:USER:
|
|
||||||
.. parsed-literal:: /Users/$USER/Library/Application Support/Blender/|BLENDER_VERSION|/
|
.. 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|\\
|
.. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
|
||||||
|
|
||||||
.. note::
|
Microsoft Store installation:
|
||||||
|
|
||||||
For installations from the Window's Store, the ``USER`` and ``SYSTEM``
|
|
||||||
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.
|
|
||||||
|
@ -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).
|
||||||
|
@ -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
|
||||||
|
@ -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/>`__.
|
||||||
|
|
||||||
|
@ -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
|
||||||
============================
|
============================
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
Loading…
Reference in New Issue
Block a user