LuxCoreRender Wiki - User contributions [en]

Deploying LuxCoreRender

2026-05-05T20:31:11Z

CodeHD: /* Documentation and Announcements */

= Audience, Definitions and Scope =

This document is intended for LuxCoreRender administrators only.

The process requires that the administrator running Release and Deploy be:
* granted with sufficient rights on LuxCoreRender repositories on Github, including running actions, producing releases etc.
* granted with sufficient rights on LuxCoreRender repository on PyPI and PyPI-test, including adding and deleting versions
* skilled enough in Github administration and, especially, able to run Github actions
* and skilled enough in PyPI administration
Please check that you meet these criteria before reading further.

In this document:
* Releasing refers to the process of finalizing a version of LuxCore, i.e. defining a state of LuxCore which can be made available to end-users.
* Deployment refers to the process of making a new release of LuxCoreRender available to end-users.

The scope of Deployment includes the following components:
* Python Wheels (aka <code>pyluxcore</code>)
* Samples (aka <code>luxcoreui</code> and <code>luxcoreconsole</code>)
* BlendLuxCore

Please note we deliberately exclude the dependencies (aka <code>LuxCoreDeps</code>) from the deployment scope. Indeed:
* Dependencies are not intended for end-users, so deployment is not applicable.
* Up-to-date dependencies are necessary for LuxCore development and tests, so they should have been released for a while when LuxCore deployment occurs.

= Prequisites =

== Clean Branches ==

The procedure assumes the releases can be created from the default branches in each repository, namely (2026-04-19):
* <code>master</code> for LuxCore
* <code>main</code> for BlendLuxCore
Please check the above branches contain all the history you target for your releases and, if not, please make the required git plumbing.

== LuxCore Buildability ==

The procedure requires that targeted LuxCore components be buildable by Continuous Integration.

This can be checked by running the following Github Actions:
* Wheels: <code>LuxCore Python Wheel Builder</code> (in LuxCore repository)
* Samples: <code>LuxCore Python Sample Builder</code> (in LuxCore repository)
* BlendLuxCore: <code>BlendLuxCore Build Bundle</code> (in BlendLuxCore)

Please check the components meet those requirements before any Release/Deploy task is engaged.

== Change Log readiness ==

At a certain point in the process, a change log will be expected: you should have prepared it beforehand. Note this can be done afterwards, however.

== Consistent Version Numbers ==
First, note you'll need 2 version numbers:
* One for LuxCore
* One for BlendLuxCore
There is no reason why these 2 version numbers should be the same.

These version numbers must enforce Semantic Versioning, as stated in [[Building_LuxCoreRender | Building LuxCoreRender]]

Please note also that the version numbers should not have been used in anyway in previous releases. It is particularly important for PyPI (and PyPI-test), that will reject any upload declaring a version that has already been in use before, event for a short time.

== Sufficient space on PyPI and PyPI-test ==

The space on PyPI and PyPI-test is limited to 10GB (as of now, 2026-04-19).

At first glance, this could look quite comfortable, however we release 20 wheels each time (about 80-100MB each): the space required for one release is about 1.5GB. As a consequence, the space sufficiency must be checked each time a version has to be deployed.

Nota: this check is critical and should be done with care. If the upload to PyPI is interrupted halfway, for instance by lack of space, the version number will still become no more available.

= Procedure =

== Pre-Flight Review ==
As stated above, before starting the core procedure, carry out the following actions:

* Ensure the default branches are up-to-date
* Check LuxCore buildability: run the 3 actions listed above.
* Ensure the change log is available
* Define and check Release Version Numbers (one for LuxCore and one for BlendLuxCore): they should have been neither allocated before, and the LuxCore should not have been used on PyPI.
* Check the space on PyPI and PyPI-test. If not sufficient, clean oldest versions.

Afterwards, you are ready to start the core process.

== Wheels Release and Deployment ==

* Set the <code>version</code> parameter in <code>build-system/conan/conanfile.py</code> to the targeted version number for LuxCore.

* Run action <code>LuxCore Python Wheels Releaser</code>, with the following settings:
Branch: <code>master</code>
Version: the version number you selected before
Update existing release (if any): unchecked
Rebuild all: checked

This will build the wheels and create a release in draft mode.

* Open the draft release and set its status to <code>prerelease</code> or <code>latest release</code>. Also, insert the change log in the release text. Save the release.

At this stage, the wheels are released, but we still have to deploy them through PyPI.

* Run action <code>LuxCore Python Wheels Publisher</code>, with the following settings:
Branch: <code>master</code>
Version: the version number you selected before
Run on PyPI test: checked
This will upload the wheels to PyPI test (deployment - test).
This is a test step, to check everything is fine before uploadig to real PyPI.

* Run action <code>LuxCore Python Wheels Publisher</code>, with the following settings:
Branch: <code>master</code>
Version: the version number you selected before
Run on PyPI test: unchecked
This will upload the wheels to PyPI (deployment).

At this stage, if everything succeeded, wheels are available for any user, with <code>pip install pyluxcore == <version> </code>. You may want to test and/or have a look on PyPI.

== Samples Release and Deployment ==

Nota #1: This step should be skipped for alpha releases, as the vast majority of alpha testers use Blender for testing. No need for samples in this context...

Nota #2: We assume the wheels have just been released, so that it is possible to reuse their build artifacts. This will be done by clearing 'rebuild all' in the following action.

* Run Github action named <code>LuxCore Samples Releaser</code>, with the following settings:
Branch: main
Version: the version number you selected before
Update existing release (if any): unchecked
Rebuild all: unchecked

At this stage, a draft release should have been created.

* Open the draft release, insert change log and set release status to <code>prerelease</code> or <code>latest release</code>.

* For latest releases, publish the files on the website

== BlendLuxCore Release and Deployment ==

Important warning: BLC should not be released while related wheels have not been deployed yet. Indeed, <code>pyluxcore</code> version must be known before starting any release or deploy action of BLC.Once that requirement is met:

* In <code>luxloader/__init__.py</code>, set <code>PYLUXCORE_VERSION</code> to the version of related <code>pyluxcore</code>. The version to use must be strictly the same as the one that appears on PyPI. Please check syntax carefully, as PyPI may slightly modify version number when uploading.

* In <code>blender_manifest.toml</code>, set <code>version</code> parameter to the targeted version of BLC. Caveat: this version can differ from pyluxcore version defined above.

* Commit your changes and push to BlendLuxCore repository, if needed.

* Run Github action named <code>BlendLuxCore Create Release</code>, with the following settings:
Branch: main
Version: the version number you selected before
Update existing release (if any): Unchecked

At this stage, a draft release should have been created.

* Open the draft release, insert change log and set release status to <code>prerelease</code> or <code>latest release</code>.

* For latest releases, publish the files on the website

== Documentation and Announcements ==

Part of the process of releasing a software is to create a proper documentation, both to support future development and to provide users with the necessary information to work efficiently with the software.
Furthermore, the final step after release and deployment is to announce the release to the community.

The following items are currently - as of v2.11 - particularly important and should be checked and well considered before a final release:
* This wiki, particularly
** Release notes
** FAQ entries
** Updates to the build process
** Description of new features, API and SDL documentation
* The project website
** particularly the downloads section
* The README files in all active code repositories
* The AUTHORS file and credits list
** specifically regarding 3rd-party modules that may have been added to the code
* Announcement on the forums
* Announcement in the discord channel
* Announcement on Blenderartist, ...

During the various release steps (alpha, beta, release candidate, stable and subsequent bugfixes), the different items may be completed to varying degrees, reaching maturity towards the stable release. The following are suggestions based on past experience. You can always look at past releases for inspiration.

==== Alpha ====
* Update the release notes
* Update the API/SDL description
* Check the authors file and credits list
* Brief GitHub release notes with warning labels about stability
* Announcement on the most active user channels
* Decide on final tasks/known bugs that shall be fixed during alpha/beta phase

==== Beta ====
* Keep updating release notes and API/SDL documentation
* Update the Readme files in the code base
* Start preparing a summary release notes for the GitHub release
* Announcement of beta phase on more community channels
* Complete all tasks for features/known bugfixes

==== Release Candidate ====
* All documentation shall be updated fully
* Update FAQs with feedback from alpha/beta phase
* Double check authors and credits
* GitHub release notes still should contain a warning label
* Start preparing stable release announcement messages for all channels

==== Stable (X.Y.0) ====
* Double-check all documentation
* Prepare the final release notes summary
* Create the release
* Update the download section on the website
* Create the announcement post on the forums
* Finally, announce on Discord and optionally other sites

==== Bugfix (X.Y.Z) ====
For bugfix releases, prepare the following
* Update the Release Notes on this wiki
* Prepare a summary release notes targeted at users
** This needs to only include the incremental changes from the previous version
* Make a short announcement on the same channels as the for the stable release

Deploying LuxCoreRender

2026-05-05T20:30:54Z

CodeHD: /* Documentation and Announcements */

= Audience, Definitions and Scope =

This document is intended for LuxCoreRender administrators only.

The process requires that the administrator running Release and Deploy be:
* granted with sufficient rights on LuxCoreRender repositories on Github, including running actions, producing releases etc.
* granted with sufficient rights on LuxCoreRender repository on PyPI and PyPI-test, including adding and deleting versions
* skilled enough in Github administration and, especially, able to run Github actions
* and skilled enough in PyPI administration
Please check that you meet these criteria before reading further.

In this document:
* Releasing refers to the process of finalizing a version of LuxCore, i.e. defining a state of LuxCore which can be made available to end-users.
* Deployment refers to the process of making a new release of LuxCoreRender available to end-users.

The scope of Deployment includes the following components:
* Python Wheels (aka <code>pyluxcore</code>)
* Samples (aka <code>luxcoreui</code> and <code>luxcoreconsole</code>)
* BlendLuxCore

Please note we deliberately exclude the dependencies (aka <code>LuxCoreDeps</code>) from the deployment scope. Indeed:
* Dependencies are not intended for end-users, so deployment is not applicable.
* Up-to-date dependencies are necessary for LuxCore development and tests, so they should have been released for a while when LuxCore deployment occurs.

= Prequisites =

== Clean Branches ==

The procedure assumes the releases can be created from the default branches in each repository, namely (2026-04-19):
* <code>master</code> for LuxCore
* <code>main</code> for BlendLuxCore
Please check the above branches contain all the history you target for your releases and, if not, please make the required git plumbing.

== LuxCore Buildability ==

The procedure requires that targeted LuxCore components be buildable by Continuous Integration.

This can be checked by running the following Github Actions:
* Wheels: <code>LuxCore Python Wheel Builder</code> (in LuxCore repository)
* Samples: <code>LuxCore Python Sample Builder</code> (in LuxCore repository)
* BlendLuxCore: <code>BlendLuxCore Build Bundle</code> (in BlendLuxCore)

Please check the components meet those requirements before any Release/Deploy task is engaged.

== Change Log readiness ==

At a certain point in the process, a change log will be expected: you should have prepared it beforehand. Note this can be done afterwards, however.

== Consistent Version Numbers ==
First, note you'll need 2 version numbers:
* One for LuxCore
* One for BlendLuxCore
There is no reason why these 2 version numbers should be the same.

These version numbers must enforce Semantic Versioning, as stated in [[Building_LuxCoreRender | Building LuxCoreRender]]

Please note also that the version numbers should not have been used in anyway in previous releases. It is particularly important for PyPI (and PyPI-test), that will reject any upload declaring a version that has already been in use before, event for a short time.

== Sufficient space on PyPI and PyPI-test ==

The space on PyPI and PyPI-test is limited to 10GB (as of now, 2026-04-19).

At first glance, this could look quite comfortable, however we release 20 wheels each time (about 80-100MB each): the space required for one release is about 1.5GB. As a consequence, the space sufficiency must be checked each time a version has to be deployed.

Nota: this check is critical and should be done with care. If the upload to PyPI is interrupted halfway, for instance by lack of space, the version number will still become no more available.

= Procedure =

== Pre-Flight Review ==
As stated above, before starting the core procedure, carry out the following actions:

* Ensure the default branches are up-to-date
* Check LuxCore buildability: run the 3 actions listed above.
* Ensure the change log is available
* Define and check Release Version Numbers (one for LuxCore and one for BlendLuxCore): they should have been neither allocated before, and the LuxCore should not have been used on PyPI.
* Check the space on PyPI and PyPI-test. If not sufficient, clean oldest versions.

Afterwards, you are ready to start the core process.

== Wheels Release and Deployment ==

* Set the <code>version</code> parameter in <code>build-system/conan/conanfile.py</code> to the targeted version number for LuxCore.

* Run action <code>LuxCore Python Wheels Releaser</code>, with the following settings:
Branch: <code>master</code>
Version: the version number you selected before
Update existing release (if any): unchecked
Rebuild all: checked

This will build the wheels and create a release in draft mode.

* Open the draft release and set its status to <code>prerelease</code> or <code>latest release</code>. Also, insert the change log in the release text. Save the release.

At this stage, the wheels are released, but we still have to deploy them through PyPI.

* Run action <code>LuxCore Python Wheels Publisher</code>, with the following settings:
Branch: <code>master</code>
Version: the version number you selected before
Run on PyPI test: checked
This will upload the wheels to PyPI test (deployment - test).
This is a test step, to check everything is fine before uploadig to real PyPI.

* Run action <code>LuxCore Python Wheels Publisher</code>, with the following settings:
Branch: <code>master</code>
Version: the version number you selected before
Run on PyPI test: unchecked
This will upload the wheels to PyPI (deployment).

At this stage, if everything succeeded, wheels are available for any user, with <code>pip install pyluxcore == <version> </code>. You may want to test and/or have a look on PyPI.

== Samples Release and Deployment ==

Nota #1: This step should be skipped for alpha releases, as the vast majority of alpha testers use Blender for testing. No need for samples in this context...

Nota #2: We assume the wheels have just been released, so that it is possible to reuse their build artifacts. This will be done by clearing 'rebuild all' in the following action.

* Run Github action named <code>LuxCore Samples Releaser</code>, with the following settings:
Branch: main
Version: the version number you selected before
Update existing release (if any): unchecked
Rebuild all: unchecked

At this stage, a draft release should have been created.

* Open the draft release, insert change log and set release status to <code>prerelease</code> or <code>latest release</code>.

* For latest releases, publish the files on the website

== BlendLuxCore Release and Deployment ==

Important warning: BLC should not be released while related wheels have not been deployed yet. Indeed, <code>pyluxcore</code> version must be known before starting any release or deploy action of BLC.Once that requirement is met:

* In <code>luxloader/__init__.py</code>, set <code>PYLUXCORE_VERSION</code> to the version of related <code>pyluxcore</code>. The version to use must be strictly the same as the one that appears on PyPI. Please check syntax carefully, as PyPI may slightly modify version number when uploading.

* In <code>blender_manifest.toml</code>, set <code>version</code> parameter to the targeted version of BLC. Caveat: this version can differ from pyluxcore version defined above.

* Commit your changes and push to BlendLuxCore repository, if needed.

* Run Github action named <code>BlendLuxCore Create Release</code>, with the following settings:
Branch: main
Version: the version number you selected before
Update existing release (if any): Unchecked

At this stage, a draft release should have been created.

* Open the draft release, insert change log and set release status to <code>prerelease</code> or <code>latest release</code>.

* For latest releases, publish the files on the website

== Documentation and Announcements ==
'''THIS SECTION IS WORK IN PROGRESS (CodeHD, 23.04.2026)'''

Part of the process of releasing a software is to create a proper documentation, both to support future development and to provide users with the necessary information to work efficiently with the software.
Furthermore, the final step after release and deployment is to announce the release to the community.

The following items are currently - as of v2.11 - particularly important and should be checked and well considered before a final release:
* This wiki, particularly
** Release notes
** FAQ entries
** Updates to the build process
** Description of new features, API and SDL documentation
* The project website
** particularly the downloads section
* The README files in all active code repositories
* The AUTHORS file and credits list
** specifically regarding 3rd-party modules that may have been added to the code
* Announcement on the forums
* Announcement in the discord channel
* Announcement on Blenderartist, ...

During the various release steps (alpha, beta, release candidate, stable and subsequent bugfixes), the different items may be completed to varying degrees, reaching maturity towards the stable release. The following are suggestions based on past experience. You can always look at past releases for inspiration.

==== Alpha ====
* Update the release notes
* Update the API/SDL description
* Check the authors file and credits list
* Brief GitHub release notes with warning labels about stability
* Announcement on the most active user channels
* Decide on final tasks/known bugs that shall be fixed during alpha/beta phase

==== Beta ====
* Keep updating release notes and API/SDL documentation
* Update the Readme files in the code base
* Start preparing a summary release notes for the GitHub release
* Announcement of beta phase on more community channels
* Complete all tasks for features/known bugfixes

==== Release Candidate ====
* All documentation shall be updated fully
* Update FAQs with feedback from alpha/beta phase
* Double check authors and credits
* GitHub release notes still should contain a warning label
* Start preparing stable release announcement messages for all channels

==== Stable (X.Y.0) ====
* Double-check all documentation
* Prepare the final release notes summary
* Create the release
* Update the download section on the website
* Create the announcement post on the forums
* Finally, announce on Discord and optionally other sites

==== Bugfix (X.Y.Z) ====
For bugfix releases, prepare the following
* Update the Release Notes on this wiki
* Prepare a summary release notes targeted at users
** This needs to only include the incremental changes from the previous version
* Make a short announcement on the same channels as the for the stable release

Deploying LuxCoreRender

2026-04-23T18:21:13Z

CodeHD: /* Announcements */

= Audience, Definitions and Scope =

This document is intended for LuxCoreRender administrators only.

The process requires that the administrator running Release and Deploy be:
* granted with sufficient rights on LuxCoreRender repositories on Github, including running actions, producing releases etc.
* granted with sufficient rights on LuxCoreRender repository on PyPI and PyPI-test, including adding and deleting versions
* skilled enough in Github administration and, especially, able to run Github actions
* and skilled enough in PyPI administration
Please check that you meet these criteria before reading further.

In this document:
* Releasing refers to the process of finalizing a version of LuxCore, i.e. defining a state of LuxCore which can be made available to end-users.
* Deployment refers to the process of making a new release of LuxCoreRender available to end-users.

The scope of Deployment includes the following components:
* Python Wheels (aka <code>pyluxcore</code>)
* Samples (aka <code>luxcoreui</code> and <code>luxcoreconsole</code>)
* BlendLuxCore

Please note we deliberately exclude the dependencies (aka <code>LuxCoreDeps</code>) from the deployment scope. Indeed:
* Dependencies are not intended for end-users, so deployment is not applicable.
* Up-to-date dependencies are necessary for LuxCore development and tests, so they should have been released for a while when LuxCore deployment occurs.

= Prequisites =

== Clean Branches ==

The procedure assumes the releases can be created from the default branches in each repository, namely (2026-04-19):
* <code>master</code> for LuxCore
* <code>main</code> for BlendLuxCore
Please check the above branches contain all the history you target for your releases and, if not, please make the required git plumbing.

== LuxCore Buildability ==

The procedure requires that targeted LuxCore components be buildable by Continuous Integration.

This can be checked by running the following Github Actions:
* Wheels: <code>LuxCore Python Wheel Builder</code> (in LuxCore repository)
* Samples: <code>LuxCore Python Sample Builder</code> (in LuxCore repository)
* BlendLuxCore: <code>BlendLuxCore Build Bundle</code> (in BlendLuxCore)

Please check the components meet those requirements before any Release/Deploy task is engaged.

== Change Log readiness ==

At a certain point in the process, a change log will be expected: you should have prepared it beforehand. Note this can be done afterwards, however.

== Consistent Version Numbers ==
First, note you'll need 2 version numbers:
* One for LuxCore
* One for BlendLuxCore
There is no reason why these 2 version numbers should be the same.

These version numbers must enforce Semantic Versioning, as stated in [[Building_LuxCoreRender | Building LuxCoreRender]]

Please note also that the version numbers should not have been used in anyway in previous releases. It is particularly important for PyPI (and PyPI-test), that will reject any upload declaring a version that has already been in use before, event for a short time.

== Sufficient space on PyPI and PyPI-test ==

The space on PyPI and PyPI-test is limited to 10GB (as of now, 2026-04-19).

At first glance, this could look quite comfortable, however we release 20 wheels each time (about 80-100MB each): the space required for one release is about 1.5GB. As a consequence, the space sufficiency must be checked each time a version has to be deployed.

Nota: this check is critical and should be done with care. If the upload to PyPI is interrupted halfway, for instance by lack of space, the version number will still become no more available.

= Procedure =

== Pre-Flight Review ==
As stated above, before starting the core procedure, carry out the following actions:

* Ensure the default branches are up-to-date
* Check LuxCore buildability: run the 3 actions listed above.
* Ensure the change log is available
* Define and check Release Version Numbers (one for LuxCore and one for BlendLuxCore): they should have been neither allocated before, and the LuxCore should not have been used on PyPI.
* Check the space on PyPI and PyPI-test. If not sufficient, clean oldest versions.

Afterwards, you are ready to start the core process.

== Wheels Release and Deployment ==

* Set the <code>version</code> parameter in <code>build-system/conan/conanfile.py</code> to the targeted version number for LuxCore.

* Run action <code>LuxCore Python Wheels Releaser</code>, with the following settings:
Branch: <code>master</code>
Version: the version number you selected before
Update existing release (if any): unchecked
Rebuild all: checked

This will build the wheels and create a release in draft mode.

* Open the draft release and set its status to <code>prerelease</code> or <code>latest release</code>. Also, insert the change log in the release text. Save the release.

At this stage, the wheels are released, but we still have to deploy them through PyPI.

* Run action <code>LuxCore Python Wheels Publisher</code>, with the following settings:
Branch: <code>master</code>
Version: the version number you selected before
Run on PyPI test: checked
This will upload the wheels to PyPI test (deployment - test).
This is a test step, to check everything is fine before uploadig to real PyPI.

* Run action <code>LuxCore Python Wheels Publisher</code>, with the following settings:
Branch: <code>master</code>
Version: the version number you selected before
Run on PyPI test: unchecked
This will upload the wheels to PyPI (deployment).

At this stage, if everything succeeded, wheels are available for any user, with <code>pip install pyluxcore == <version> </code>. You may want to test and/or have a look on PyPI.

== Samples Release and Deployment ==

Nota #1: This step should be skipped for alpha releases, as the vast majority of alpha testers use Blender for testing. No need for samples in this context...

Nota #2: We assume the wheels have just been released, so that it is possible to reuse their build artifacts. This will be done by clearing 'rebuild all' in the following action.

* Run Github action named <code>LuxCore Samples Releaser</code>, with the following settings:
Branch: main
Version: the version number you selected before
Update existing release (if any): unchecked
Rebuild all: unchecked

At this stage, a draft release should have been created.

* Open the draft release, insert change log and set release status to <code>prerelease</code> or <code>latest release</code>.

* For latest releases, publish the files on the website

== BlendLuxCore Release and Deployment ==

Important warning: BLC should not be released while related wheels have not been deployed yet. Indeed, <code>pyluxcore</code> version must be known before starting any release or deploy action of BLC.Once that requirement is met:

* In <code>luxloader/__init__.py</code>, set <code>PYLUXCORE_VERSION</code> to the version of related <code>pyluxcore</code>. The version to use must be strictly the same as the one that appears on PyPI. Please check syntax carefully, as PyPI may slightly modify version number when uploading.

* In <code>blender_manifest.toml</code>, set <code>version</code> parameter to the targeted version of BLC. Caveat: this version can differ from pyluxcore version defined above.

* Commit your changes and push to BlendLuxCore repository, if needed.

* Run Github action named <code>BlendLuxCore Create Release</code>, with the following settings:
Branch: main
Version: the version number you selected before
Update existing release (if any): Unchecked

At this stage, a draft release should have been created.

* Open the draft release, insert change log and set release status to <code>prerelease</code> or <code>latest release</code>.

* For latest releases, publish the files on the website

== Documentation and Announcements ==
'''THIS SECTION IS WORK IN PROGRESS (CodeHD, 23.04.2026)'''

Part of the process of releasing a software is to create a proper documentation, both to support future development and to provide users with the necessary information to work efficiently with the software.
Furthermore, the final step after release and deployment is to announce the release to the communicate.

The following items are currently - as of v2.11 - particularly important and should be checked and well considered before a final release:
* This wiki
** particularly the pages linked on the front page
* The project website
** particularly the downloads section
* The README files in all active code repositories
* The AUTHORS file and credits list
** specifically regarding 3rd-party modules that may have been added to the code
* Announcement on the forums
* Announcement in the discord channel
* Announcement on Blenderartist

During the various release steps (alpha, beta, release candidate, stable and subsequent bugfixes), the different items may be completed to varying degrees, reaching maturity towards the stable release. The following are suggestions based on past experience. You can always look at past releases for inspiration.

==== Alpha ====

==== Beta ====

==== Release Candidate ====

==== Stable (X.Y.0) ====
At this point, all

==== Bugfix (X.Y.Z) ====
For bugfix releases, prepare the following
* Update the Release Notes on this wiki
* Prepare a summary release notes targeted at users
** This needs to only include the incremental changes from the previous version
* Make a short announcement on the same channels as the Stable release

BlendLuxCore FAQ

2026-04-11T10:21:03Z

CodeHD: /* I can not enable the BlendLuxCore addon, it shows errors */

= Frequently Asked Questions =

=== When trying to use CUDA/OptiX, Blender crashes ===

This can be a different manifestation of the issue described below (CUDA_ERROR_UNSUPPORTED_PTX_VERSION). Try to upgrade the nvidia driver to the latest version, or try the studio driver branches for a latest stable version.

Specifically, this has been observed with nvrtc13 in combination with drivers <590.

=== When trying to use CUDA/OptiX, I get the error message: <code>RUNTIME ERROR: CUDA driver API error CUDA_ERROR_UNSUPPORTED_PTX_VERSION (code: 222, file:.../cuda.cpp, line: xxx): the provided PTX was compiled with an unsupported toolchain.</code> ===

Your nvidia driver is too old compared to nvidia runtime compiler used by LuxCore, so the code compiled by LuxCore runtime compiler cannot be run by your driver.

Please upgrade your nvidia driver to latest version, or at least to a suitable version with regard to runtime compiler: https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#id7

=== After installation, I get the error message "could not import pyluxcore" ===

"pyluxcore" is the binary core library. BlendLuxCore downloads and installs the correct version for your system during installation. This error indicates something went wrong with this installation. Possible solutions are:
* Check that online access is allowed in the Blender preferences.
* Download may be restricted in company networks. You can try an [https://wiki.luxcorerender.org/BlendLuxCore_Installation#Offline_Installation offline-installation].

=== I can not enable the BlendLuxCore addon, it shows errors ===

'''Note: This section applies to older BlendLuxCore versions up to v2.9alpha'''

Most problems in this area stem from broken graphics driver installations. Try to re-install or update your graphics driver.

'''For Windows users:'''
* Make sure that you have installed the [https://www.microsoft.com/en-US/download/details.aspx?id=40784 Visual C++ Redistributable Packages for Visual Studio 2013]
* If you use v2.1alpha0 or later, you will also need:
** [https://aka.ms/vs/15/release/vc_redist.x64.exe Microsoft Visual C++ Redistributable for Visual Studio 2017]
** [https://software.intel.com/sites/default/files/managed/59/aa/ww_icl_redist_msi_2018.3.210.zip Intel C++ redistributable]

If this does not solve the problem, browse the [https://github.com/LuxCoreRender/BlendLuxCore/issues?q=is%3Aissue+label%3Ainstallation installation issues] in the bug tracker to check if your error message was already reported.
If it was not reported yet, open a new issue and copy the error message from the Blender console (on Windows, click Window -> Toggle System Console in Blender's menu. On Linux, start Blender from a terminal and try to enable the addon, then copy the error message from the terminal).

See the [[BlendLuxCore_Installation | installation page]] for information on how to install, update and remove the BlendLuxCore addon.

=== Is there something like Cycles' Layer Weight/Fresnel/Facing node in LuxCore? ===

No, in LuxCore there is no direct equivalent to this node, because it would not work with the many algorithms in LuxCore that trace rays from lights (instead of from the camera), like the bidirectional engine, light tracing mode, or the PhotonGI cache.

Of course, all materials in LuxCore are physically based and have realistic fresnel effects built-in.

You can achieve a similar effect with the dot product node, but it will work only for one viewpoint:

[[File:Layer_weight_for_one_direction.PNG | thumb | 400px | center]]

=== Can Cycles materials be used in BlendLuxCore? ===

To an extent, yes. Many common Cycles shader nodes can be used in BlendLuxCore:

* You can enable this individually for each material with the "Use Cycles Nodes" option in the material properties.
* You can also enable it for the whole scene at once with the "Use Cycles Settings" button in the render properties. This will configure all materials, lights and the world to use Cycles settings

Not all Cycles nodes and settings are supported. Here is an overview: https://github.com/LuxCoreRender/BlendLuxCore/issues/272

=== Can 2D/3D mapping be driven by textures in LuxCore? ===

In general, no, because it would lead to much worse performance on GPUs.

However, if you only need to drive the translation part of a texture mapping, since LuxCore v2.5 you can use the distort texture for this purpose:

[[File:Distort_texture.PNG | thumb | 400px | center | A checker texture (left) is distorted by a clouds texture (right). The result can be seen in the center]]

Texturing of rotation and scale is not yet possible.

=== What can be done against fireflies/hotpixels? ===

Sometimes, pixels appear that are much brighter than the surrounding pixels. Sometimes they are singular, sometimes clumped up. The underlying reason are light paths that are correct, but very hard to find with the current rendering algorithms, and thus they take much longer to render until noise-free than all other light paths in the image.

There are multiple ways to approach this problem:

* '''Try another rendering algorithm''', it might be able to find the firefly-causing light paths much easier than the one you currently use. For example, try going to the render properties, open the Light Paths panel and enable "Light Tracing", or try the [[PhotonGI | PhotonGI caustic cache]], or try using the bidirectional engine.
* You can '''clamp the brightness of all light paths''' to a maximum value, in the render properties, Light Paths panel, "Clamping" setting. BlendLuxCore can auto-detect a value for this setting that is in the right ballpark for your scene if you render once without clamping enabled, but often this value will not be the best, so you will need a bit of trial-and-error to find a good value. Note that the clamping value depends on the lighting in your scene, so there is no one universally good clamping value, and you might need to adjust it if you add a new light source to your scene that is brighter than the others. Using a clamping value that is too low will result in a low-contrast, washed-out image, while a too high value will leave fireflies unaffected.
* Try to find out which lights or materials are responsible for the fireflies. There might be small, hard-to-find light sources that are causing them. Or a specular material is reflecting such a light source. If you are willing to alter the look of the scene, you can make such a light source more visible/larger, or lower the specularity of such a material. You can also make some light sources invisble to indirect light rays, thus eliminating fireflies (light properties, "Visibility" panel). This can be a good idea for the sun, for example, if your scene contains lots of specular materials.

=== Why is my HDRI environment black and not showing up? ===
You probably have other very bright light sources in the scene, for example a sun or a sky lamp.

'''Solution:''' raise the gain value of the area or HDRI light source that is black. The gain value might need to be very high, e.g. 100000.

=== Why is my area lamp black? ===
See [[#"Why is my HDRI environment black and not showing up?"]]

=== When I change the brightness of my lamp, nothing happens ===

You are probably using an automatic tonemapper which adjusts itself to the changed brightness, making it seem like the brightness did not change.

'''Solution:''' Use a non-automatic tonemapper (camera settings -> [[ImagePipeline]]).


=== When I make one of my lights brighter, all the other lights get darker (or vice versa) ===

Similar to [[#"When I change the brightness of my lamp, nothing happens"]]. 
You are using an automatic tonemapper which tries to keep the image at the same brightness, making it seem like the brightness of the lamps changed.

'''Solution:''' Use a non-automatic tonemapper (camera settings -> [[ImagePipeline]]).


=== A material/object appears to be flickering when I move the camera and shows artifacts in final render ===

This effect is called [https://en.wikipedia.org/wiki/Z-fighting Z-fighting] and is usually caused by mesh faces being exactly on top of each other, e.g. two planes on the same world coordinates.

'''Solution:'''
* Check if there are two objects on top of each other, e.g. because you duplicated the object, cancelled the transform and forgot about it.
* Check if the mesh has duplicate faces. Enter edit mode and use the Remove Doubles button in the Tools panel, which might solve the problem in some cases.
Duplicate faces are often caused by extruding, cancelling the transform and forgetting about it.

=== There are dark triangular artifacts on my model, and I already checked for duplicate faces ===

Floating point numbers have a limited precision. When objects are very large (kilometers) or very small (micrometers), these precision issues become visible.

'''Solution:'''
* If the object has a "normal" size (something like 1 cm to 1 km), but was scaled up/down by a huge amount, try to apply the scale (Ctrl+A -> Scale). For example, this often happens with imported CAD models.
* If applying the scale did not help and your object has to be very small or large, consider to bring it into the normal scale mentioned above, and pretend that it has a larger/smaller size. For example, if you make a model of the solar system, you will just have to make the earth something like 12.742 m in diameter, and pretend that 1 m of your model is equal to 10^6 m.
* If both options above are not usable in your case, you can raise the minimum epsilon that LuxCore uses. This setting can be found in the scene properties, Units panel, after clicking "Advanced LuxCore Settings". By default, the minimum epsilon is 0.00001. Try to raise it to 0.0001 (multiply by 10) for a start and see if the artifacts disappear. Do not set this value higher than necessary, because it will cause all sorts of hard-to-track problems. Be especially careful if you are rendering a scene with volumes.

=== An object that I set to "smooth shading" looks like it is shaded flat in shadow penumbras ===

This artifact is called "terminator problem".

'''Solution:''' Unfortunately there is no real solution. You can only try to mitigate the effect by subdividing the geometry further and/or increase the size of the light source that is causing the problem.

=== How do I setup liquid in a glass container correctly? ===

This forum thread shows an example: https://forums.luxcorerender.org/viewtopic.php?f=4&t=728#p7550

=== Can I export my scene in LuxCore format to render it in LuxCore standalone? ===

Yes. In the render properties, LuxCore Tools panel, enable "FileSaver". Then render with F12.

=== How can I compile kernels from the command line? ===
Here is a way to compile kernels from the command line (out of Blender), for the latest version of pyluxcore:
<pre>
pip install pyluxcore --upgrade
python -c "import pyluxcore; pyluxcore.Init(); pyluxcore.KernelCacheFill()"
</pre>

= Getting Help =

If none of the above entries helped to solve your problem, consider asking in the [https://forums.luxcorerender.org/viewforum.php?f=4 user support forum] or [https://forums.luxcorerender.org/viewtopic.php?f=4&t=2 filing a bug report].

[[Category:BlendLuxCore]]

BlendLuxCore FAQ

2026-04-11T10:19:04Z

CodeHD: Add a new section about CUDA/OptiX

= Frequently Asked Questions =

=== When trying to use CUDA/OptiX, Blender crashes ===

This can be a different manifestation of the issue described below (CUDA_ERROR_UNSUPPORTED_PTX_VERSION). Try to upgrade the nvidia driver to the latest version, or try the studio driver branches for a latest stable version.

Specifically, this has been observed with nvrtc13 in combination with drivers <590.

=== When trying to use CUDA/OptiX, I get the error message: <code>RUNTIME ERROR: CUDA driver API error CUDA_ERROR_UNSUPPORTED_PTX_VERSION (code: 222, file:.../cuda.cpp, line: xxx): the provided PTX was compiled with an unsupported toolchain.</code> ===

Your nvidia driver is too old compared to nvidia runtime compiler used by LuxCore, so the code compiled by LuxCore runtime compiler cannot be run by your driver.

Please upgrade your nvidia driver to latest version, or at least to a suitable version with regard to runtime compiler: https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#id7

=== After installation, I get the error message "could not import pyluxcore" ===

"pyluxcore" is the binary core library. BlendLuxCore downloads and installs the correct version for your system during installation. This error indicates something went wrong with this installation. Possible solutions are:
* Check that online access is allowed in the Blender preferences.
* Download may be restricted in company networks. You can try an [https://wiki.luxcorerender.org/BlendLuxCore_Installation#Offline_Installation offline-installation].

=== I can not enable the BlendLuxCore addon, it shows errors ===

Most problems in this area stem from broken graphics driver installations. Try to re-install or update your graphics driver.

'''For Windows users:'''
* Make sure that you have installed the [https://www.microsoft.com/en-US/download/details.aspx?id=40784 Visual C++ Redistributable Packages for Visual Studio 2013]
* If you use v2.1alpha0 or later, you will also need:
** [https://aka.ms/vs/15/release/vc_redist.x64.exe Microsoft Visual C++ Redistributable for Visual Studio 2017]
** [https://software.intel.com/sites/default/files/managed/59/aa/ww_icl_redist_msi_2018.3.210.zip Intel C++ redistributable]

If this does not solve the problem, browse the [https://github.com/LuxCoreRender/BlendLuxCore/issues?q=is%3Aissue+label%3Ainstallation installation issues] in the bug tracker to check if your error message was already reported.
If it was not reported yet, open a new issue and copy the error message from the Blender console (on Windows, click Window -> Toggle System Console in Blender's menu. On Linux, start Blender from a terminal and try to enable the addon, then copy the error message from the terminal).

See the [[BlendLuxCore_Installation | installation page]] for information on how to install, update and remove the BlendLuxCore addon.

=== Is there something like Cycles' Layer Weight/Fresnel/Facing node in LuxCore? ===

No, in LuxCore there is no direct equivalent to this node, because it would not work with the many algorithms in LuxCore that trace rays from lights (instead of from the camera), like the bidirectional engine, light tracing mode, or the PhotonGI cache.

Of course, all materials in LuxCore are physically based and have realistic fresnel effects built-in.

You can achieve a similar effect with the dot product node, but it will work only for one viewpoint:

[[File:Layer_weight_for_one_direction.PNG | thumb | 400px | center]]

=== Can Cycles materials be used in BlendLuxCore? ===

To an extent, yes. Many common Cycles shader nodes can be used in BlendLuxCore:

* You can enable this individually for each material with the "Use Cycles Nodes" option in the material properties.
* You can also enable it for the whole scene at once with the "Use Cycles Settings" button in the render properties. This will configure all materials, lights and the world to use Cycles settings

Not all Cycles nodes and settings are supported. Here is an overview: https://github.com/LuxCoreRender/BlendLuxCore/issues/272

=== Can 2D/3D mapping be driven by textures in LuxCore? ===

In general, no, because it would lead to much worse performance on GPUs.

However, if you only need to drive the translation part of a texture mapping, since LuxCore v2.5 you can use the distort texture for this purpose:

[[File:Distort_texture.PNG | thumb | 400px | center | A checker texture (left) is distorted by a clouds texture (right). The result can be seen in the center]]

Texturing of rotation and scale is not yet possible.

=== What can be done against fireflies/hotpixels? ===

Sometimes, pixels appear that are much brighter than the surrounding pixels. Sometimes they are singular, sometimes clumped up. The underlying reason are light paths that are correct, but very hard to find with the current rendering algorithms, and thus they take much longer to render until noise-free than all other light paths in the image.

There are multiple ways to approach this problem:

* '''Try another rendering algorithm''', it might be able to find the firefly-causing light paths much easier than the one you currently use. For example, try going to the render properties, open the Light Paths panel and enable "Light Tracing", or try the [[PhotonGI | PhotonGI caustic cache]], or try using the bidirectional engine.
* You can '''clamp the brightness of all light paths''' to a maximum value, in the render properties, Light Paths panel, "Clamping" setting. BlendLuxCore can auto-detect a value for this setting that is in the right ballpark for your scene if you render once without clamping enabled, but often this value will not be the best, so you will need a bit of trial-and-error to find a good value. Note that the clamping value depends on the lighting in your scene, so there is no one universally good clamping value, and you might need to adjust it if you add a new light source to your scene that is brighter than the others. Using a clamping value that is too low will result in a low-contrast, washed-out image, while a too high value will leave fireflies unaffected.
* Try to find out which lights or materials are responsible for the fireflies. There might be small, hard-to-find light sources that are causing them. Or a specular material is reflecting such a light source. If you are willing to alter the look of the scene, you can make such a light source more visible/larger, or lower the specularity of such a material. You can also make some light sources invisble to indirect light rays, thus eliminating fireflies (light properties, "Visibility" panel). This can be a good idea for the sun, for example, if your scene contains lots of specular materials.

=== Why is my HDRI environment black and not showing up? ===
You probably have other very bright light sources in the scene, for example a sun or a sky lamp.

'''Solution:''' raise the gain value of the area or HDRI light source that is black. The gain value might need to be very high, e.g. 100000.

=== Why is my area lamp black? ===
See [[#"Why is my HDRI environment black and not showing up?"]]

=== When I change the brightness of my lamp, nothing happens ===

You are probably using an automatic tonemapper which adjusts itself to the changed brightness, making it seem like the brightness did not change.

'''Solution:''' Use a non-automatic tonemapper (camera settings -> [[ImagePipeline]]).


=== When I make one of my lights brighter, all the other lights get darker (or vice versa) ===

Similar to [[#"When I change the brightness of my lamp, nothing happens"]]. 
You are using an automatic tonemapper which tries to keep the image at the same brightness, making it seem like the brightness of the lamps changed.

'''Solution:''' Use a non-automatic tonemapper (camera settings -> [[ImagePipeline]]).


=== A material/object appears to be flickering when I move the camera and shows artifacts in final render ===

This effect is called [https://en.wikipedia.org/wiki/Z-fighting Z-fighting] and is usually caused by mesh faces being exactly on top of each other, e.g. two planes on the same world coordinates.

'''Solution:'''
* Check if there are two objects on top of each other, e.g. because you duplicated the object, cancelled the transform and forgot about it.
* Check if the mesh has duplicate faces. Enter edit mode and use the Remove Doubles button in the Tools panel, which might solve the problem in some cases.
Duplicate faces are often caused by extruding, cancelling the transform and forgetting about it.

=== There are dark triangular artifacts on my model, and I already checked for duplicate faces ===

Floating point numbers have a limited precision. When objects are very large (kilometers) or very small (micrometers), these precision issues become visible.

'''Solution:'''
* If the object has a "normal" size (something like 1 cm to 1 km), but was scaled up/down by a huge amount, try to apply the scale (Ctrl+A -> Scale). For example, this often happens with imported CAD models.
* If applying the scale did not help and your object has to be very small or large, consider to bring it into the normal scale mentioned above, and pretend that it has a larger/smaller size. For example, if you make a model of the solar system, you will just have to make the earth something like 12.742 m in diameter, and pretend that 1 m of your model is equal to 10^6 m.
* If both options above are not usable in your case, you can raise the minimum epsilon that LuxCore uses. This setting can be found in the scene properties, Units panel, after clicking "Advanced LuxCore Settings". By default, the minimum epsilon is 0.00001. Try to raise it to 0.0001 (multiply by 10) for a start and see if the artifacts disappear. Do not set this value higher than necessary, because it will cause all sorts of hard-to-track problems. Be especially careful if you are rendering a scene with volumes.

=== An object that I set to "smooth shading" looks like it is shaded flat in shadow penumbras ===

This artifact is called "terminator problem".

'''Solution:''' Unfortunately there is no real solution. You can only try to mitigate the effect by subdividing the geometry further and/or increase the size of the light source that is causing the problem.

=== How do I setup liquid in a glass container correctly? ===

This forum thread shows an example: https://forums.luxcorerender.org/viewtopic.php?f=4&t=728#p7550

=== Can I export my scene in LuxCore format to render it in LuxCore standalone? ===

Yes. In the render properties, LuxCore Tools panel, enable "FileSaver". Then render with F12.

=== How can I compile kernels from the command line? ===
Here is a way to compile kernels from the command line (out of Blender), for the latest version of pyluxcore:
<pre>
pip install pyluxcore --upgrade
python -c "import pyluxcore; pyluxcore.Init(); pyluxcore.KernelCacheFill()"
</pre>

= Getting Help =

If none of the above entries helped to solve your problem, consider asking in the [https://forums.luxcorerender.org/viewforum.php?f=4 user support forum] or [https://forums.luxcorerender.org/viewtopic.php?f=4&t=2 filing a bug report].

[[Category:BlendLuxCore]]

LuxCoreRender Release Notes v2.11

2026-04-03T11:53:15Z

CodeHD: sorting entries

= BlendLuxCore =
'''Coding/Backend'''
* Include "OptiX" in addon settings label to avoid user questions about compatibility
* Remove leftover code from the Addons system that is no longer used with the Extensions system.
* Use LuxCore internal OIDN (rather than embedding and calling an external OIDN executable)

'''Bugfix'''
* Added a workaround for a Blender bug that throws an error when Blender is closed https://projects.blender.org/blender/blender/issues/140488
* Limit float values in viewport render to 16-bit in order to avoid overexposed areas being displayed as black.
* Fix rounding of convergence percentage, reaching 100% to early for complex scenes
* Fix Blender crash when clicking Copy Material

'''Features for users'''
* Update compatibility for Blender 5.0
* Fresnel texture: "custom n,k" now accepts values > 1
* Remove default filtering of Intel GPU devices
* Add a checkbox to the material output node for enabling an override: When using shadow color, this allows light rays in addition to the shadow rays. (default off == no light rays, only shadow rays)
* 2D-mapping: Add an option to allow rotation around the center of UV-coordinate space (c.f. section LuxCore)
* New shape node "MergeOnDistance" (like Blender Merge by Distance)
* Subdiv: (simple) crease management

= BlendLuxHelper =
* Adding BlendLuxHelper: A new helper, in the form of a Blender extension, which allows to configure the wheel that is imported by BlendLuxCore.
* <del>Change installation mechanism to use bpy.utils.extension_path_user()</del> (Reworked within the scope of BlendLuxHelper)
* <del>Added a Linux development shell script (optional utility for developers)</del> (replaced by BlendLuxHelper)

= LuxCore =

'''Coding/Backend'''
* Subdivision: multithreaded version, in order to improve speed
* Reduction of Boost footprint, replaced with standard equivalents available in C++20.
* For the need of previous point: replacement of apple-clang by clang 20 on MacOS platforms
* New target 'wheel-test' that builds a testing wheel in local build (<code>make wheel-test</code>)
* Requirement checking in <code>make deps</code>
* luxrays: rename GetConfigDir as GetCacheDir and use XDG_CACHE_HOME according to specifications (@illwieckz)
* Adapt CI pipelines to MacOS-15 runners (after deprecation of MacOS-13 runners on Github)
* Remove direct access to Blender internal objects. Use Blender API instead, more stable.
* Add support for Python 3.14 (and remove support for 3.9)

'''Bugfix'''
* Fix a bug leading to unstable brightness between renderings when using saved crashes (Credit to FELIX Render developers)
* Fix volume evaluation in BiDir engine https://github.com/LuxCoreRender/LuxCore/issues/647
* Fix various bugs when using orthographic camera with light tracing https://github.com/LuxCoreRender/LuxCore/issues/667
* Fix various memory-related issues (leaks, potential access violations...). Modernize memory handling (to be continued)
* Avoid crash if no OpenCL and/or Nvidia API is found
* Fix several race conditions
* Fixed an error where paused renderings can't be stopped anymore
* 3D-mapping: Fix inconsistent behavior between local and random-local mapping https://github.com/LuxCoreRender/BlendLuxCore/issues/656

'''Features for users'''
* Subdivision: add an "adaptive" setting to select between adaptive refinement and uniform refinement
* Make `pyluxcoretools` available again (in the wheels)
* Apply the behavior of the BiDir engine w.r.t. shadow color mechanism to Path+Light tracing. Breaking change for scenes using shadow color and light tracing (not BiDir)! https://github.com/LuxCoreRender/LuxCore/issues/671
* 2D-mapping: Add an option to allow rotation around the center of UV-coordinate space https://github.com/LuxCoreRender/BlendLuxCore/issues/644

= LuxCoreDeps =
* Dependencies updated to latest versions
* Better dependency pinning (for nvrtc and conan-index)
* Removed a workaround introduced in previous version (we used to build a fake wheel to get containerization)
* OpenMP - MacOS: Use of homebrew OpenMP (up-to-date, compatible with clang 20) rather than Conan llvm-openmp (version 17...). As a consequence, for MacOS Intel, a version >= 13.0 is required.
* Opensubdiv: tbb activation. As a consequence, for MacOS Arm, a version >= 14.2 is required.
* OpenImageIO: deactivation of several image formats that seem unrelated to or unsupported by LuxCore: freetype, hdf5, ffmpeg, libheif, ptex, opencv, webp. This removal spares both compilation time and build result size. Those formats are reactivable, in case they were missing.
* OpenImageIO: To the contrary, activation of tbb option.
* Embree: Upgraded to version 4.
* libjpeg: Replaced with libjpeg-turbo

LuxCoreRender Release Notes v2.11

2026-04-02T11:41:38Z

CodeHD: /* BlendLuxCore */

= BlendLuxCore =

* Fresnel texture: "custom n,k" now accepts values > 1
* Include "OptiX" in addon settings label to avoid user questions about compatibility
* Added a workaround for a Blender bug that throws an error when Blender is closed https://projects.blender.org/blender/blender/issues/140488
* Remove leftover code from the Addons system that is no longer used with the Extensions system.
* Limit float values in viewport render to 16-bit in order to avoid overexposed areas being displayed as black.
* Remove default filtering of Intel GPU devices
* Add a checkbox to the material output node for enabling an override: When using shadow color, this allows light rays in addition to the shadow rays. (default off == no light rays, only shadow rays)
* Fix rounding of convergence percentage, reaching 100% to early for complex scenes
* Update compatibility for Blender 5.0
* 2D-mapping: Add an option to allow rotation around the center of UV-coordinate space (c.f. section LuxCore(

= BlendLuxHelper =
* Adding BlendLuxHelper: A new helper, in the form of a Blender extension, which allows to configure the wheel that is imported by BlendLuxCore.
* <del>Change installation mechanism to use bpy.utils.extension_path_user()</del> (Reworked within the scope of BlendLuxHelper)
* <del>Added a Linux development shell script (optional utility for developers)</del> (replaced by BlendLuxHelper)

= LuxCore =
* Reduction of Boost footprint, replaced with standard equivalents available in C++20.
* For the need of previous point: replacement of apple-clang by clang 20 on MacOS platforms
* New target 'wheel-test' that builds a testing wheel in local build (<code>make wheel-test</code>)
* Requirement checking in <code>make deps</code>
* luxrays: rename GetConfigDir as GetCacheDir and use XDG_CACHE_HOME according to specifications (@illwieckz)
* Subdivision: add an "adaptive" setting to select between adaptive refinement and uniform refinement
* Subdivision: multithreaded version
* Fix a bug leading to unstable brightness between renderings when using saved crashes (Credit to FELIX Render developers)
* Fix volume evaluation in BiDir engine https://github.com/LuxCoreRender/LuxCore/issues/647
* Fix various bugs when using orthographic camera with light tracing https://github.com/LuxCoreRender/LuxCore/issues/667
* Apply the behavior of the BiDir engine w.r.t. shadow color mechanism to Path+Light tracing. Breaking change for scenes using shadow color and light tracing (not BiDir)! https://github.com/LuxCoreRender/LuxCore/issues/671
* Fixed an error where paused renderings can't be stopped anymore
* 2D-mapping: Add an option to allow rotation around the center of UV-coordinate space https://github.com/LuxCoreRender/BlendLuxCore/issues/644
* 3D-mapping: Fix inconsistent behavior between local and random-local mapping https://github.com/LuxCoreRender/BlendLuxCore/issues/656

= LuxCoreDeps =
* Dependencies updated to latest versions
* Removed a workaround introduced in previous version (we used to build a fake wheel to get containerization)
* OpenMP - MacOS: Use of homebrew OpenMP (up-to-date, compatible with clang 20) rather than Conan llvm-openmp (version 17...). As a consequence, for MacOS Intel, a version >= 13.0 is required.
* Opensubdiv: tbb activation. As a consequence, for MacOS Arm, a version >= 14.2 is required.
* OpenImageIO: deactivation of several image formats that seem unrelated to or unsupported by LuxCore: freetype, hdf5, ffmpeg, libheif, ptex, opencv, webp. This removal spares both compilation time and build result size. Those formats are reactivable, in case they were missing.
* OpenImageIO: To the contrary, activation of tbb option.
* Embree: Upgraded to version 4.
* libjpeg: Replaced with libjpeg-turbo

LuxCoreRender Release Notes v2.11

2026-04-02T11:41:03Z

CodeHD: /* LuxCore */

= BlendLuxCore =

* Fresnel texture: "custom n,k" now accepts values > 1
* Include "OptiX" in addon settings label to avoid user questions about compatibility
* Added a workaround for a Blender bug that throws an error when Blender is closed https://projects.blender.org/blender/blender/issues/140488
* Remove leftover code from the Addons system that is no longer used with the Extensions system.
* Limit float values in viewport render to 16-bit in order to avoid overexposed areas being displayed as black.
* Remove default filtering of Intel GPU devices
* Add a checkbox to the material output node for enabling an override: When using shadow color, this allows light rays in addition to the shadow rays. (default off == no light rays, only shadow rays)
* Fix rounding of convergence percentage, reaching 100% to early for complex scenes
* Update compatibility for Blender 5.0
* 2D-mapping: Add an option to allow rotation around the center of UV-coordinate space

= BlendLuxHelper =
* Adding BlendLuxHelper: A new helper, in the form of a Blender extension, which allows to configure the wheel that is imported by BlendLuxCore.
* <del>Change installation mechanism to use bpy.utils.extension_path_user()</del> (Reworked within the scope of BlendLuxHelper)
* <del>Added a Linux development shell script (optional utility for developers)</del> (replaced by BlendLuxHelper)

= LuxCore =
* Reduction of Boost footprint, replaced with standard equivalents available in C++20.
* For the need of previous point: replacement of apple-clang by clang 20 on MacOS platforms
* New target 'wheel-test' that builds a testing wheel in local build (<code>make wheel-test</code>)
* Requirement checking in <code>make deps</code>
* luxrays: rename GetConfigDir as GetCacheDir and use XDG_CACHE_HOME according to specifications (@illwieckz)
* Subdivision: add an "adaptive" setting to select between adaptive refinement and uniform refinement
* Subdivision: multithreaded version
* Fix a bug leading to unstable brightness between renderings when using saved crashes (Credit to FELIX Render developers)
* Fix volume evaluation in BiDir engine https://github.com/LuxCoreRender/LuxCore/issues/647
* Fix various bugs when using orthographic camera with light tracing https://github.com/LuxCoreRender/LuxCore/issues/667
* Apply the behavior of the BiDir engine w.r.t. shadow color mechanism to Path+Light tracing. Breaking change for scenes using shadow color and light tracing (not BiDir)! https://github.com/LuxCoreRender/LuxCore/issues/671
* Fixed an error where paused renderings can't be stopped anymore
* 2D-mapping: Add an option to allow rotation around the center of UV-coordinate space https://github.com/LuxCoreRender/BlendLuxCore/issues/644
* 3D-mapping: Fix inconsistent behavior between local and random-local mapping https://github.com/LuxCoreRender/BlendLuxCore/issues/656

= LuxCoreDeps =
* Dependencies updated to latest versions
* Removed a workaround introduced in previous version (we used to build a fake wheel to get containerization)
* OpenMP - MacOS: Use of homebrew OpenMP (up-to-date, compatible with clang 20) rather than Conan llvm-openmp (version 17...). As a consequence, for MacOS Intel, a version >= 13.0 is required.
* Opensubdiv: tbb activation. As a consequence, for MacOS Arm, a version >= 14.2 is required.
* OpenImageIO: deactivation of several image formats that seem unrelated to or unsupported by LuxCore: freetype, hdf5, ffmpeg, libheif, ptex, opencv, webp. This removal spares both compilation time and build result size. Those formats are reactivable, in case they were missing.
* OpenImageIO: To the contrary, activation of tbb option.
* Embree: Upgraded to version 4.
* libjpeg: Replaced with libjpeg-turbo

LuxCoreRender Release Notes v2.11

2026-04-02T11:34:31Z

CodeHD: /* BlendLuxCore */

= BlendLuxCore =

* Fresnel texture: "custom n,k" now accepts values > 1
* Include "OptiX" in addon settings label to avoid user questions about compatibility
* Added a workaround for a Blender bug that throws an error when Blender is closed https://projects.blender.org/blender/blender/issues/140488
* Remove leftover code from the Addons system that is no longer used with the Extensions system.
* Limit float values in viewport render to 16-bit in order to avoid overexposed areas being displayed as black.
* Remove default filtering of Intel GPU devices
* Add a checkbox to the material output node for enabling an override: When using shadow color, this allows light rays in addition to the shadow rays. (default off == no light rays, only shadow rays)
* Fix rounding of convergence percentage, reaching 100% to early for complex scenes
* Update compatibility for Blender 5.0
* 2D-mapping: Add an option to allow rotation around the center of UV-coordinate space

= BlendLuxHelper =
* Adding BlendLuxHelper: A new helper, in the form of a Blender extension, which allows to configure the wheel that is imported by BlendLuxCore.
* <del>Change installation mechanism to use bpy.utils.extension_path_user()</del> (Reworked within the scope of BlendLuxHelper)
* <del>Added a Linux development shell script (optional utility for developers)</del> (replaced by BlendLuxHelper)

= LuxCore =
* Reduction of Boost footprint, replaced with standard equivalents available in C++20.
* For the need of previous point: replacement of apple-clang by clang 20 on MacOS platforms
* New target 'wheel-test' that builds a testing wheel in local build (<code>make wheel-test</code>)
* Requirement checking in <code>make deps</code>
* luxrays: rename GetConfigDir as GetCacheDir and use XDG_CACHE_HOME according to specifications (@illwieckz)
* Subdivision: add an "adaptive" setting to select between adaptive refinement and uniform refinement
* Subdivision: multithreaded version
* Fix a bug leading to unstable brightness between renderings when using saved crashes (Credit to FELIX Render developers)
* Fix volume evaluation in BiDir engine https://github.com/LuxCoreRender/LuxCore/issues/647
* Fix various bugs when using orthographic camera with light tracing https://github.com/LuxCoreRender/LuxCore/issues/667
* Apply the behavior of the BiDir engine w.r.t. shadow color mechanism to Path+Light tracing. Breaking change for scenes using shadow color and light tracing (not BiDir)!

= LuxCoreDeps =
* Dependencies updated to latest versions
* Removed a workaround introduced in previous version (we used to build a fake wheel to get containerization)
* OpenMP - MacOS: Use of homebrew OpenMP (up-to-date, compatible with clang 20) rather than Conan llvm-openmp (version 17...). As a consequence, for MacOS Intel, a version >= 13.0 is required.
* Opensubdiv: tbb activation. As a consequence, for MacOS Arm, a version >= 14.2 is required.
* OpenImageIO: deactivation of several image formats that seem unrelated to or unsupported by LuxCore: freetype, hdf5, ffmpeg, libheif, ptex, opencv, webp. This removal spares both compilation time and build result size. Those formats are reactivable, in case they were missing.
* OpenImageIO: To the contrary, activation of tbb option.
* Embree: Upgraded to version 4.
* libjpeg: Replaced with libjpeg-turbo

LuxCoreRender Release Notes v2.11

2026-04-02T11:30:03Z

CodeHD: Split BlendLuxHelper into its own category

= BlendLuxCore =

* Fresnel texture: "custom n,k" now accepts values > 1

* Include "OptiX" in addon settings label to avoid user questions about compatibility
* Added a workaround for a Blender bug that throws an error when Blender is closed
* Remove leftover code from the Addons system that is no longer used with the Extensions system.
* Limit float values in viewport render to 16-bit in order to avoid overexposed areas being displayed as black.
* Remove default filtering of Intel GPU devices
* Add a checkbox to the material output node for enabling an override: When using shadow color, this allows light rays in addition to the shadow rays. (default off == no light rays, only shadow rays)

= BlendLuxHelper =
* Adding BlendLuxHelper: A new helper, in the form of a Blender extension, which allows to configure the wheel that is imported by BlendLuxCore.
* <del>Change installation mechanism to use bpy.utils.extension_path_user()</del> (Reworked within the scope of BlendLuxHelper)
* <del>Added a Linux development shell script (optional utility for developers)</del> (replaced by BlendLuxHelper)

= LuxCore =
* Reduction of Boost footprint, replaced with standard equivalents available in C++20.
* For the need of previous point: replacement of apple-clang by clang 20 on MacOS platforms
* New target 'wheel-test' that builds a testing wheel in local build (<code>make wheel-test</code>)
* Requirement checking in <code>make deps</code>
* luxrays: rename GetConfigDir as GetCacheDir and use XDG_CACHE_HOME according to specifications (@illwieckz)
* Subdivision: add an "adaptive" setting to select between adaptive refinement and uniform refinement
* Subdivision: multithreaded version
* Fix a bug leading to unstable brightness between renderings when using saved crashes (Credit to FELIX Render developers)
* Fix volume evaluation in BiDir engine https://github.com/LuxCoreRender/LuxCore/issues/647
* Fix various bugs when using orthographic camera with light tracing https://github.com/LuxCoreRender/LuxCore/issues/667
* Apply the behavior of the BiDir engine w.r.t. shadow color mechanism to Path+Light tracing. Breaking change for scenes using shadow color and light tracing (not BiDir)!

= LuxCoreDeps =
* Dependencies updated to latest versions
* Removed a workaround introduced in previous version (we used to build a fake wheel to get containerization)
* OpenMP - MacOS: Use of homebrew OpenMP (up-to-date, compatible with clang 20) rather than Conan llvm-openmp (version 17...). As a consequence, for MacOS Intel, a version >= 13.0 is required.
* Opensubdiv: tbb activation. As a consequence, for MacOS Arm, a version >= 14.2 is required.
* OpenImageIO: deactivation of several image formats that seem unrelated to or unsupported by LuxCore: freetype, hdf5, ffmpeg, libheif, ptex, opencv, webp. This removal spares both compilation time and build result size. Those formats are reactivable, in case they were missing.
* OpenImageIO: To the contrary, activation of tbb option.
* Embree: Upgraded to version 4.
* libjpeg: Replaced with libjpeg-turbo

LuxCoreRender Release Notes v2.10

2025-10-23T20:30:56Z

CodeHD: /* BlendLuxCore */

__TOC__

=Bugfix release v2.10.2=

===LuxCore===

===BlendLuxCore===
* Fix an issue with the blendev utility script and the .gitignore file
* Remove some filtering of Intel devices left from times when iGPU devices were not powerful enough
* Remove deprecated bgl imports, to establish preliminary compatibility with Blender 5.0.0-beta
* Change the calculation of percentage completion when using noise threshold to avoid the display being stuck at 100% before the rendering is actually finished

=Bugfix release v2.10.1=

===LuxCore===
* Fixed a bug in luxcoreui (crash when loading a new .cfg file)
* Pin nvrtc dependency of pyluxcore to a specific version

===BlendLuxCore===
* Added a workaround for a Blender bug that throws an error when Blender is closed: [https://projects.blender.org/blender/blender/issues/140488 Blender Issue Tracker]
* Added a linux development shell script (optional utility for developers, [https://wiki.luxcorerender.org/Developing_and_debugging_BlendLuxCore#Utility_shell_script_for_launching_Blender see here])
* Viewport: Limit values in extremely overexposed areas, previously causing these areas to appear black

=LuxCore=

===New Features===

* New, multiplatform dependency manager: LuxCoreDeps. The new dep manager is based on Conan, an open source software which gives access to a database of thousands of build recipes, maintained up-to-date both by a company (JFrog) and a dynamic community. The deps are now built from sources, for a better control of build settings, binary compatibility etc.

* Dependencies updated to latest versions

* Buildability restored for all previous platforms: Linux, Windows, MacOS Intel

* Buildability added MacOS ARM platform.

* LuxCoreRender delivered in the form of Python wheels, published on PyPi.

* Automation (check, build, publish...) rewritten in Github Actions

===Fixed Bugs===

* LuxCore is now buildable again, on all previous platforms (Linux, Windows, MacOS Intel) + one (MacOS ARM).
* Crash fixed on tile path

===Known Problems===

= BlendLuxCore =

===New Features===
* Compatibility for Blender 4.2 and 4.3
* Partial compatibility for Blender 4.4 (not a release goal)
* Moved from Blenders addon system to the new extension system
* BlendLuxCore no longer bundles LuxCore binaries, platform specific binaries now distributed via PyPi
* Changed build pipeline from Azure to GitHub CI/CD
* Add square-root option to math node (alias to power 0.5)
* Add a setting to suppress LuxCore console log output
* Glass material now accepts IOR < 1
* Materials can now be individually excluded from material override
* BlendLuxCore specific menus are marked with an icon

===Fixed Bugs===
* Motion blur support for instances
* Improve custom normals export time by utilizing mesh.loops.foreach_get()
* LOL: Changed data access to adapt to new webhosting requirements

===Known Problems===
* Crashes are observed on macOS with Blender 4.2 and Blender 4.3. Related to window resizing and render completion. Unknown if Blender specific or also happening in standalone.
* Motion blur does not seem to work on "deeper iterations", e.g. copying an instanced object

LuxCoreRender Release Notes v2.10

2025-10-23T19:53:42Z

CodeHD: /* BlendLuxCore */

__TOC__

=Bugfix release v2.10.2=

===LuxCore===

===BlendLuxCore===
* fix an issue with the blendev utility script and the .gitignore file
* Remove some filtering of Intel devices left from times when iGPU devices were not powerful enough
* Remove deprecated bgl imports, to establish preliminary compatibility with Blender 5.0.0-beta
* Change the calculation of percentage completion when using noise threshold to avoid the display being stuck at 100% before the rendering is actually finished

=Bugfix release v2.10.1=

===LuxCore===
* Fixed a bug in luxcoreui (crash when loading a new .cfg file)
* Pin nvrtc dependency of pyluxcore to a specific version

===BlendLuxCore===
* Added a workaround for a Blender bug that throws an error when Blender is closed: [https://projects.blender.org/blender/blender/issues/140488 Blender Issue Tracker]
* Added a linux development shell script (optional utility for developers, [https://wiki.luxcorerender.org/Developing_and_debugging_BlendLuxCore#Utility_shell_script_for_launching_Blender see here])
* Viewport: Limit values in extremely overexposed areas, previously causing these areas to appear black

=LuxCore=

===New Features===

* New, multiplatform dependency manager: LuxCoreDeps. The new dep manager is based on Conan, an open source software which gives access to a database of thousands of build recipes, maintained up-to-date both by a company (JFrog) and a dynamic community. The deps are now built from sources, for a better control of build settings, binary compatibility etc.

* Dependencies updated to latest versions

* Buildability restored for all previous platforms: Linux, Windows, MacOS Intel

* Buildability added MacOS ARM platform.

* LuxCoreRender delivered in the form of Python wheels, published on PyPi.

* Automation (check, build, publish...) rewritten in Github Actions

===Fixed Bugs===

* LuxCore is now buildable again, on all previous platforms (Linux, Windows, MacOS Intel) + one (MacOS ARM).
* Crash fixed on tile path

===Known Problems===

= BlendLuxCore =

===New Features===
* Compatibility for Blender 4.2 and 4.3
* Partial compatibility for Blender 4.4 (not a release goal)
* Moved from Blenders addon system to the new extension system
* BlendLuxCore no longer bundles LuxCore binaries, platform specific binaries now distributed via PyPi
* Changed build pipeline from Azure to GitHub CI/CD
* Add square-root option to math node (alias to power 0.5)
* Add a setting to suppress LuxCore console log output
* Glass material now accepts IOR < 1
* Materials can now be individually excluded from material override
* BlendLuxCore specific menus are marked with an icon

===Fixed Bugs===
* Motion blur support for instances
* Improve custom normals export time by utilizing mesh.loops.foreach_get()
* LOL: Changed data access to adapt to new webhosting requirements

===Known Problems===
* Crashes are observed on macOS with Blender 4.2 and Blender 4.3. Related to window resizing and render completion. Unknown if Blender specific or also happening in standalone.
* Motion blur does not seem to work on "deeper iterations", e.g. copying an instanced object

LuxCoreRender Release Notes v2.10

2025-10-23T19:50:52Z

CodeHD: Add section for v2.10.2

__TOC__

=Bugfix release v2.10.2=

===LuxCore===

===BlendLuxCore===

=Bugfix release v2.10.1=

===LuxCore===
* Fixed a bug in luxcoreui (crash when loading a new .cfg file)
* Pin nvrtc dependency of pyluxcore to a specific version

===BlendLuxCore===
* Added a workaround for a Blender bug that throws an error when Blender is closed: [https://projects.blender.org/blender/blender/issues/140488 Blender Issue Tracker]
* Added a linux development shell script (optional utility for developers, [https://wiki.luxcorerender.org/Developing_and_debugging_BlendLuxCore#Utility_shell_script_for_launching_Blender see here])
* Viewport: Limit values in extremely overexposed areas, previously causing these areas to appear black

=LuxCore=

===New Features===

* New, multiplatform dependency manager: LuxCoreDeps. The new dep manager is based on Conan, an open source software which gives access to a database of thousands of build recipes, maintained up-to-date both by a company (JFrog) and a dynamic community. The deps are now built from sources, for a better control of build settings, binary compatibility etc.

* Dependencies updated to latest versions

* Buildability restored for all previous platforms: Linux, Windows, MacOS Intel

* Buildability added MacOS ARM platform.

* LuxCoreRender delivered in the form of Python wheels, published on PyPi.

* Automation (check, build, publish...) rewritten in Github Actions

===Fixed Bugs===

* LuxCore is now buildable again, on all previous platforms (Linux, Windows, MacOS Intel) + one (MacOS ARM).
* Crash fixed on tile path

===Known Problems===

= BlendLuxCore =

===New Features===
* Compatibility for Blender 4.2 and 4.3
* Partial compatibility for Blender 4.4 (not a release goal)
* Moved from Blenders addon system to the new extension system
* BlendLuxCore no longer bundles LuxCore binaries, platform specific binaries now distributed via PyPi
* Changed build pipeline from Azure to GitHub CI/CD
* Add square-root option to math node (alias to power 0.5)
* Add a setting to suppress LuxCore console log output
* Glass material now accepts IOR < 1
* Materials can now be individually excluded from material override
* BlendLuxCore specific menus are marked with an icon

===Fixed Bugs===
* Motion blur support for instances
* Improve custom normals export time by utilizing mesh.loops.foreach_get()
* LOL: Changed data access to adapt to new webhosting requirements

===Known Problems===
* Crashes are observed on macOS with Blender 4.2 and Blender 4.3. Related to window resizing and render completion. Unknown if Blender specific or also happening in standalone.
* Motion blur does not seem to work on "deeper iterations", e.g. copying an instanced object

LuxCoreRender Release Notes v2.11

2025-10-11T19:20:17Z

CodeHD: /* LuxCore */

= BlendLuxCore =

* Fresnel texture: "custom n,k" now accepts values > 1
* <del>Change installation mechanism to use bpy.utils.extension_path_user()</del> (Reworked again within the scope of BlendLuxHelper)
* Include "OptiX" in addon settings label to avoid user questions about compatibility
* Added a workaround for a Blender bug that throws an error when Blender is closed
* <del>Added a Linux development shell script (optional utility for developers)</del> (replaced by BlendLuxHelper)
* Remove leftover code from the Addons system that is no longer used with the Extensions system.
* BlendLuxHelper: A new helper, in the form of a Blender extension, which allows to configure the wheel which is imported by BlendLuxCore.
* Limit float values in viewport render to 16-bit in order to avoid overexposed areas being displayed as black.
* Remove default filtering of Intel GPU devices
* Add a checkbox to the material output node for enabling an override: When using shadow color, this allows light rays in addition to the shadow rays. (default off == no light rays, only shadow rays)

= LuxCore =
* Reduction of Boost footprint, replaced with standard equivalents available in C++20.
* For the need of previous point: replacement of apple-clang by clang 20 on MacOS platforms
* New target 'wheel-test' that builds a testing wheel in local build (<code>make wheel-test</code>)
* Requirement checking in <code>make deps</code>
* luxrays: rename GetConfigDir as GetCacheDir and use XDG_CACHE_HOME according to specifications (@illwieckz)
* Subdivision: add an "adaptive" setting to select between adaptive refinement and uniform refinement
* Subdivision: multithreaded version
* Fix a bug leading to unstable brightness between renderings when using saved crashes (Credit to FELIX Render developers)
* Fix volume evaluation in BiDir engine https://github.com/LuxCoreRender/LuxCore/issues/647
* Fix various bugs when using orthographic camera with light tracing https://github.com/LuxCoreRender/LuxCore/issues/667
* Apply the behavior of the BiDir engine w.r.t. shadow color mechanism to Path+Light tracing. Breaking change for scenes using shadow color and light tracing (not BiDir)!

= LuxCoreDeps =
* Dependencies updated to latest versions
* Removed a workaround introduced in previous version (we used to build a fake wheel to get containerization)
* OpenMP - MacOS: Use of homebrew OpenMP (up-to-date, compatible with clang 20) rather than Conan llvm-openmp (version 17...). As a consequence, for MacOS Intel, a version >= 13.0 is required.
* Opensubdiv: tbb activation. As a consequence, for MacOS Arm, a version >= 14.2 is required.
* OpenImageIO: deactivation of several image formats that seem unrelated to or unsupported by LuxCore: freetype, hdf5, ffmpeg, libheif, ptex, opencv, webp. This removal spares both compilation time and build result size. Those formats are reactivable, in case they were missing.
* OpenImageIO: To the contrary, activation of tbb option.
* Embree: Upgraded to version 4.
* libjpeg: Replaced with libjpeg-turbo

LuxCoreRender Release Notes v2.11

2025-10-11T19:10:31Z

CodeHD: /* BlendLuxCore */

= BlendLuxCore =

* Fresnel texture: "custom n,k" now accepts values > 1
* <del>Change installation mechanism to use bpy.utils.extension_path_user()</del> (Reworked again within the scope of BlendLuxHelper)
* Include "OptiX" in addon settings label to avoid user questions about compatibility
* Added a workaround for a Blender bug that throws an error when Blender is closed
* <del>Added a Linux development shell script (optional utility for developers)</del> (replaced by BlendLuxHelper)
* Remove leftover code from the Addons system that is no longer used with the Extensions system.
* BlendLuxHelper: A new helper, in the form of a Blender extension, which allows to configure the wheel which is imported by BlendLuxCore.
* Limit float values in viewport render to 16-bit in order to avoid overexposed areas being displayed as black.
* Remove default filtering of Intel GPU devices
* Add a checkbox to the material output node for enabling an override: When using shadow color, this allows light rays in addition to the shadow rays. (default off == no light rays, only shadow rays)

= LuxCore =
* Reduction of Boost footprint, replaced with standard equivalents available in C++20.
* For the need of previous point: replacement of apple-clang by clang 20 on MacOS platforms
* New target 'wheel-test' that builds a testing wheel in local build (<code>make wheel-test</code>)
* Requirement checking in <code>make deps</code>
* luxrays: rename GetConfigDir as GetCacheDir and use XDG_CACHE_HOME according to specifications (@illwieckz)
* Subdivision: add an "adaptive" setting to select between adaptive refinement and uniform refinement
* Subdivision: multithreaded version

= LuxCoreDeps =
* Dependencies updated to latest versions
* Removed a workaround introduced in previous version (we used to build a fake wheel to get containerization)
* OpenMP - MacOS: Use of homebrew OpenMP (up-to-date, compatible with clang 20) rather than Conan llvm-openmp (version 17...). As a consequence, for MacOS Intel, a version >= 13.0 is required.
* Opensubdiv: tbb activation. As a consequence, for MacOS Arm, a version >= 14.2 is required.
* OpenImageIO: deactivation of several image formats that seem unrelated to or unsupported by LuxCore: freetype, hdf5, ffmpeg, libheif, ptex, opencv, webp. This removal spares both compilation time and build result size. Those formats are reactivable, in case they were missing.
* OpenImageIO: To the contrary, activation of tbb option.
* Embree: Upgraded to version 4.
* libjpeg: Replaced with libjpeg-turbo

Developing and debugging BlendLuxCore

2025-10-07T19:51:03Z

CodeHD: /* Installation of BlendLuxHelper and Setup of BlendLuxCore */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper (BLH).

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment. 
Suggested name: <code>blc_dbg</code>

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender through the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts". 
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

= Scenario #2: Working on pyluxcore =

To use a custom wheel of pyluxcore, open the addon preferences of BLH.
Set the option <code>Wheel Source</code> to <code>Local Wheel</code>. You can then enter a <code>Path to Wheel file</code>, which must point to the wheel itself, not the folder where it is located!

At each startup (or reload), BLC computes a hash of the linked wheel. This hash is compared against information stored in a local file, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel, and update accordingly if you change the selection of <code>Wheel Source</code>.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore [...]</code> --> A local version will be used. 
<code>[BLC] installing pyluxcore version: [...]</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. [...]</code> --> BLC detected that the installed wheel matches the designated wheel, and installation is skipped. 

(Note: Further error messages exist but they are out of the scope of this article.)

= Scenario #3: Offline installation =

When you need to perform an offline installation, you first need to download the dependencies of pyluxcore as wheel-files. 
If you are unsure about the correct modules and versions, or where to get them, please ask on the support channels (Forum, Discord, ...).

In the BLH addon preferences, first configure to use a Local Wheel as described in the previous section.

Then, use the additional option <code>Path to additional dependency folder (optional)</code> to specify the path where the dependencies are located. 
In this field enter a folder path that contains all the dependency wheels that you previously downloaded. (Not a wheel directly, as required in the previous section.)

At the next startup, Blender will install the local wheel including the local dependencies.

= Tips & Tricks =

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file:

<code>$HOME/.config/blender/<blender-version>/extensions/.user/<repository>/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T19:50:50Z

CodeHD: /* Installation of BlendLuxHelper and Setup of BlendLuxCore */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper (BLH).

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.
Suggested name: <code>blc_dbg</code>

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender through the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts". 
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

= Scenario #2: Working on pyluxcore =

To use a custom wheel of pyluxcore, open the addon preferences of BLH.
Set the option <code>Wheel Source</code> to <code>Local Wheel</code>. You can then enter a <code>Path to Wheel file</code>, which must point to the wheel itself, not the folder where it is located!

At each startup (or reload), BLC computes a hash of the linked wheel. This hash is compared against information stored in a local file, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel, and update accordingly if you change the selection of <code>Wheel Source</code>.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore [...]</code> --> A local version will be used. 
<code>[BLC] installing pyluxcore version: [...]</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. [...]</code> --> BLC detected that the installed wheel matches the designated wheel, and installation is skipped. 

(Note: Further error messages exist but they are out of the scope of this article.)

= Scenario #3: Offline installation =

When you need to perform an offline installation, you first need to download the dependencies of pyluxcore as wheel-files. 
If you are unsure about the correct modules and versions, or where to get them, please ask on the support channels (Forum, Discord, ...).

In the BLH addon preferences, first configure to use a Local Wheel as described in the previous section.

Then, use the additional option <code>Path to additional dependency folder (optional)</code> to specify the path where the dependencies are located. 
In this field enter a folder path that contains all the dependency wheels that you previously downloaded. (Not a wheel directly, as required in the previous section.)

At the next startup, Blender will install the local wheel including the local dependencies.

= Tips & Tricks =

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file:

<code>$HOME/.config/blender/<blender-version>/extensions/.user/<repository>/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T19:50:09Z

CodeHD: /* Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper (BLH).

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender through the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts". 
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

= Scenario #2: Working on pyluxcore =

To use a custom wheel of pyluxcore, open the addon preferences of BLH.
Set the option <code>Wheel Source</code> to <code>Local Wheel</code>. You can then enter a <code>Path to Wheel file</code>, which must point to the wheel itself, not the folder where it is located!

At each startup (or reload), BLC computes a hash of the linked wheel. This hash is compared against information stored in a local file, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel, and update accordingly if you change the selection of <code>Wheel Source</code>.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore [...]</code> --> A local version will be used. 
<code>[BLC] installing pyluxcore version: [...]</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. [...]</code> --> BLC detected that the installed wheel matches the designated wheel, and installation is skipped. 

(Note: Further error messages exist but they are out of the scope of this article.)

= Scenario #3: Offline installation =

When you need to perform an offline installation, you first need to download the dependencies of pyluxcore as wheel-files. 
If you are unsure about the correct modules and versions, or where to get them, please ask on the support channels (Forum, Discord, ...).

In the BLH addon preferences, first configure to use a Local Wheel as described in the previous section.

Then, use the additional option <code>Path to additional dependency folder (optional)</code> to specify the path where the dependencies are located. 
In this field enter a folder path that contains all the dependency wheels that you previously downloaded. (Not a wheel directly, as required in the previous section.)

At the next startup, Blender will install the local wheel including the local dependencies.

= Tips & Tricks =

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file:

<code>$HOME/.config/blender/<blender-version>/extensions/.user/<repository>/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T19:49:32Z

CodeHD: /* Statement of problem */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper (BLH).

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender through the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts". 
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

= Scenario #2: Working on pyluxcore =

To use a custom wheel of pyluxcore, open the addon preferences of BLH.
Set the option <code>Wheel Source</code> to <code>Local Wheel</code>. You can then enter a <code>Path to Wheel file</code>, which must point to the wheel itself, not the folder where it is located!

At each startup (or reload), BLC computes a hash of the linked wheel. This hash is compared against information stored in a local file, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel, and update accordingly if you change the selection of <code>Wheel Source</code>.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore [...]</code> --> A local version will be used. 
<code>[BLC] installing pyluxcore version: [...]</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. [...]</code> --> BLC detected that the installed wheel matches the designated wheel, and installation is skipped. 

(Note: Further error messages exist but they are out of the scope of this article.)

= Scenario #3: Offline installation =

When you need to perform an offline installation, you first need to download the dependencies of pyluxcore as wheel-files. 
If you are unsure about the correct modules and versions, or where to get them, please ask on the support channels (Forum, Discord, ...).

In the BLH addon preferences, first configure to use a Local Wheel as described in the previous section.

Then, use the additional option <code>Path to additional dependency folder (optional)</code> to specify the path where the dependencies are located. 
In this field enter a folder path that contains all the dependency wheels that you previously downloaded. (Not a wheel directly, as required in the previous section.)

At the next startup, Blender will install the local wheel including the local dependencies.

= Tips & Tricks =

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file:

<code>$HOME/.config/blender/<blender-version>/extensions/.user/blc_dbg/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T19:01:06Z

CodeHD: /* Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender thorugh the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts". 
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

= Scenario #2: Working on pyluxcore =

To use a custom wheel of pyluxcore, open the addon preferences of BLH.
Set the option <code>Wheel Source</code> to <code>Local Wheel</code>. You can then enter a <code>Path to Wheel file</code>, which must point to the wheel itself, not the folder where it is located!

At each startup (or reload), BLC computes a hash of the linked wheel. This hash is compared against information stored in a local file, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel, and update accordingly if you change the selection of <code>Wheel Source</code>.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore [...]</code> --> A local version will be used. 
<code>[BLC] installing pyluxcore version: [...]</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. [...]</code> --> BLC detected that the installed wheel matches the designated wheel, and installation is skipped. 

(Note: Further error messages exist but they are out of the scope of this article.)

= Scenario #3: Offline installation =

When you need to perform an offline installation, you first need to download the dependencies of pyluxcore as wheel-files. 
If you are unsure about the correct modules and versions, or where to get them, please ask on the support channels (Forum, Discord, ...).

In the BLH addon preferences, first configure to use a Local Wheel as described in the previous section.

Then, use the additional option <code>Path to additional dependency folder (optional)</code> to specify the path where the dependencies are located. 
In this field enter a folder path that contains all the dependency wheels that you previously downloaded. (Not a wheel directly, as required in the previous section.)

At the next startup, Blender will install the local wheel including the local dependencies.

= Tips & Tricks =

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

THIS SECTION NEEDS AN UPDATE

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T19:00:17Z

CodeHD: Add offline installation option

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender thorugh the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts". 
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

= Scenario #2: Working on pyluxcore =

To use a custom wheel of pyluxcore, open the addon preferences of BLH.
Set the option <code>Wheel Source</code> to <code>Local Wheel</code>. You can then enter a <code>Path to Wheel file</code>, which must point to the wheel itself, not the folder where it is located!

At each startup (or reload), BLC computes a hash of the linked wheel. This hash is compared against information stored in a local file, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel, and update accordingly if you change the selection of <code>Wheel Source</code>.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore [...]</code> --> A local version will be used. 
<code>[BLC] installing pyluxcore version: [...]</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. [...]</code> --> BLC detected that the installed wheel matches the designated wheel, and installation is skipped. 

(Note: Further error messages exist but they are out of the scope of this article.)

= Scenario #3: Offline installation =

When you need to perform an offline installation, you first need to download the dependencies of pyluxcore as wheel-files. 
If you are unsure about the correct modules and versions, or where to get them, please ask on the support channels (Forum, Discord, ...).

In the BLH addon preferences, first configure to use a Local Wheel as described in the previous section.

Then, use the additional option <code>Path to additional dependency folder (optional)</code> to specify the path where the dependencies are located. 
In this field enter a folder path that contains all the dependency wheels that you previously downloaded. (Not a wheel directly, as required in the previous section.)

At the next startup, Blender will install the local wheel including the local dependencies.

= Tips & Tricks =

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T18:47:39Z

CodeHD: /* Tips & Tricks */ Remove obsolete sections

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender thorugh the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts". 
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

= Scenario #2: Working on pyluxcore =

To use a custom wheel of pyluxcore, open the addon preferences of BLH.
Set the option <code>Wheel Source</code> to <code>Local Wheel</code>. You can then enter a <code>Path to Wheel file</code>, which must point to the wheel itself, not the folder where it is located!

At each startup (or reload), BLC computes a hash of the linked wheel. This hash is compared against information stored in a local file, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel, and update accordingly if you change the selection of <code>Wheel Source</code>.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore [...]</code> --> A local version will be used. 
<code>[BLC] installing pyluxcore version: [...]</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. [...]</code> --> BLC detected that the installed wheel matches the designated wheel, and installation is skipped. 

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T18:47:05Z

CodeHD: /* Scenario #2: Working on pyluxcore */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender thorugh the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts". 
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

= Scenario #2: Working on pyluxcore =

To use a custom wheel of pyluxcore, open the addon preferences of BLH.
Set the option <code>Wheel Source</code> to <code>Local Wheel</code>. You can then enter a <code>Path to Wheel file</code>, which must point to the wheel itself, not the folder where it is located!

At each startup (or reload), BLC computes a hash of the linked wheel. This hash is compared against information stored in a local file, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel, and update accordingly if you change the selection of <code>Wheel Source</code>.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore [...]</code> --> A local version will be used. 
<code>[BLC] installing pyluxcore version: [...]</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. [...]</code> --> BLC detected that the installed wheel matches the designated wheel, and installation is skipped. 

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T18:39:44Z

CodeHD: /* Scenario #1: Working on BLC, using standard pyluxcore */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender thorugh the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

If you followed the previous instructions and installed BLC via a symbolic link, BLC will always be loaded from your local git repository source at Blender startup.

if you make changes to BLC and want to reload the addon, you can use Blenders internal function "Reload Scripts". 
Nota: This feature is WIP for BLC and may not yet be functional for all of its submodules.

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed Python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T18:36:05Z

CodeHD: /* Installation of BlendLuxHelper and Setup of BlendLuxCore */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender thorugh the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

Step 5: 
Close and reopen Blender. Go to the addon-preferences menu and enable the BLC addon.
The addon should now be installed, including the installation of pyluxcore and its dependencies.

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path folder containing the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set <code>BLC_DEV_PATH</code> to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that Python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all Python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed Python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T18:33:57Z

CodeHD: Add section about BLH installation

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Installation of BlendLuxHelper and Setup of BlendLuxCore =

Step 1: 
Uninstall any previously installed version of BLC.

Step 2 (optional): 
Add a new local extension repository for installation of the BLC/BLH development environment.

Step 3: 
Download the latest release of [https://github.com/LuxCoreRender/BlendLuxHelper BLH on GitHub], or - if necessary - build the extension from source.

Install BLH in Blender thorugh the extensions menu using the [https://docs.blender.org/manual/en/latest/editors/preferences/extensions.html#bpy-ops-extensions-package-install-files Install from Disk] option.

Step 4: 
Create a symbolic link to the local BLC git-repository, as outlined in Blenders Add-on Development Setup guide.
In the Addon preferences menu of BLH, at the bottom, you can find a function to perform this step with a graphical interface.

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path folder containing the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set <code>BLC_DEV_PATH</code> to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that Python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all Python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed Python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T18:21:07Z

CodeHD: /* Prerequisites */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

You made yourself familiar with Blenders official [https://developer.blender.org/docs/handbook/extensions/addon_dev_setup/ Add-on Development Setup] guide.

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path folder containing the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set <code>BLC_DEV_PATH</code> to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that Python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all Python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed Python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T18:07:30Z

CodeHD: /* Statement of problem */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

In addition, there may be the need to handle some unusual cases, for example performing an offline-installation in restrictive company networks where dependencies cannot be downloaded via pip.

To facilitate the configuration of these scenarios, we provide a separate extension, BlendLuxHelper.

The setup and usage of BlendLuxCore together with BlendLuxHelper will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path folder containing the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set <code>BLC_DEV_PATH</code> to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that Python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all Python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed Python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T17:56:07Z

CodeHD: /* Goal and audience */

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.
* Use cases with non-standard requirements, e.g. the need to perform an offline installation.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.

These methods will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path folder containing the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set <code>BLC_DEV_PATH</code> to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that Python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all Python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed Python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-10-07T17:54:55Z

CodeHD: Add note about v2.11 WIP content

= Introduction =

Note: This article is work in progress for the development of BlendLuxCore v2.11. Instructions for v2.10 can be found in the article [[Developing and debugging BlendLuxCore v2.10]] 

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.

These methods will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path folder containing the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set <code>BLC_DEV_PATH</code> to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that Python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all Python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed Python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore v2.10

2025-10-07T17:53:05Z

CodeHD: Add note about deprecation

Note: This page is documenting the development process used in v2.10.x of BlendLuxCore. The content is no longer under active development. See the main article [[Developing and debugging BlendLuxCore]] for the latest instructions.

= Introduction =

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.

These methods will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path folder containing the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set <code>BLC_DEV_PATH</code> to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that Python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all Python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed Python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore v2.10

2025-10-07T17:45:53Z

CodeHD: Created page with "= Introduction = == Goal and audience == This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. The targeted audience encompasses: * BlendLuxCore development contributors * BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature. * LuxCore developers who want to use Blender as a tool to test changes to the core eng..."

= Introduction =

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.

These methods will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path folder containing the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set <code>BLC_DEV_PATH</code> to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that Python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all Python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed Python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precedence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed Python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

LuxCoreRender Release Notes v2.10

2025-07-25T08:36:55Z

CodeHD: /* Bugfix release v2.10.1 */

__TOC__

=Bugfix release v2.10.1=

===LuxCore===
* Fixed a bug in luxcoreui (crash when loading a new .cfg file)
* Pin nvrtc dependency of pyluxcore to a specific version

===BlendLuxCore===
* Added a workaround for a Blender bug that throws an error when Blender is closed: [https://projects.blender.org/blender/blender/issues/140488 Blender Issue Tracker]
* Added a linux development shell script (optional utility for developers, [https://wiki.luxcorerender.org/Developing_and_debugging_BlendLuxCore#Utility_shell_script_for_launching_Blender see here])
* Viewport: Limit values in extremely overexposed areas, previously causing these areas to appear black

=LuxCore=

===New Features===

* New, multiplatform dependency manager: LuxCoreDeps. The new dep manager is based on Conan, an open source software which gives access to a database of thousands of build recipes, maintained up-to-date both by a company (JFrog) and a dynamic community. The deps are now built from sources, for a better control of build settings, binary compatibility etc.

* Dependencies updated to latest versions

* Buildability restored for all previous platforms: Linux, Windows, MacOS Intel

* Buildability added MacOS ARM platform.

* LuxCoreRender delivered in the form of Python wheels, published on PyPi.

* Automation (check, build, publish...) rewritten in Github Actions

===Fixed Bugs===

* LuxCore is now buildable again, on all previous platforms (Linux, Windows, MacOS Intel) + one (MacOS ARM).
* Crash fixed on tile path

===Known Problems===

= BlendLuxCore =

===New Features===
* Compatibility for Blender 4.2 and 4.3
* Partial compatibility for Blender 4.4 (not a release goal)
* Moved from Blenders addon system to the new extension system
* BlendLuxCore no longer bundles LuxCore binaries, platform specific binaries now distributed via PyPi
* Changed build pipeline from Azure to GitHub CI/CD
* Add square-root option to math node (alias to power 0.5)
* Add a setting to suppress LuxCore console log output
* Glass material now accepts IOR < 1
* Materials can now be individually excluded from material override
* BlendLuxCore specific menus are marked with an icon

===Fixed Bugs===
* Motion blur support for instances
* Improve custom normals export time by utilizing mesh.loops.foreach_get()
* LOL: Changed data access to adapt to new webhosting requirements

===Known Problems===
* Crashes are observed on macOS with Blender 4.2 and Blender 4.3. Related to window resizing and render completion. Unknown if Blender specific or also happening in standalone.
* Motion blur does not seem to work on "deeper iterations", e.g. copying an instanced object

LuxCoreRender Release Notes v2.10

2025-07-23T15:21:37Z

CodeHD: /* Bugfix release v2.10.1 */

__TOC__

=Bugfix release v2.10.1=

===LuxCore===
* Fixed a bug in luxcoreui (crash when loading a new .cfg file)
* Pin nvrtc dependency of pyluxcore to a specific version

===BlendLuxCore===
* Added a workaround for a Blender bug that throws an error when Blender is closed: [https://projects.blender.org/blender/blender/issues/140488 Blender Issue Tracker]
* Added a linux development shell script (optional utility for developers)
* Viewport: Limit values in extremely overexposed areas, previously causing these areas to appear black

=LuxCore=

===New Features===

* New, multiplatform dependency manager: LuxCoreDeps. The new dep manager is based on Conan, an open source software which gives access to a database of thousands of build recipes, maintained up-to-date both by a company (JFrog) and a dynamic community. The deps are now built from sources, for a better control of build settings, binary compatibility etc.

* Dependencies updated to latest versions

* Buildability restored for all previous platforms: Linux, Windows, MacOS Intel

* Buildability added MacOS ARM platform.

* LuxCoreRender delivered in the form of Python wheels, published on PyPi.

* Automation (check, build, publish...) rewritten in Github Actions

===Fixed Bugs===

* LuxCore is now buildable again, on all previous platforms (Linux, Windows, MacOS Intel) + one (MacOS ARM).
* Crash fixed on tile path

===Known Problems===

= BlendLuxCore =

===New Features===
* Compatibility for Blender 4.2 and 4.3
* Partial compatibility for Blender 4.4 (not a release goal)
* Moved from Blenders addon system to the new extension system
* BlendLuxCore no longer bundles LuxCore binaries, platform specific binaries now distributed via PyPi
* Changed build pipeline from Azure to GitHub CI/CD
* Add square-root option to math node (alias to power 0.5)
* Add a setting to suppress LuxCore console log output
* Glass material now accepts IOR < 1
* Materials can now be individually excluded from material override
* BlendLuxCore specific menus are marked with an icon

===Fixed Bugs===
* Motion blur support for instances
* Improve custom normals export time by utilizing mesh.loops.foreach_get()
* LOL: Changed data access to adapt to new webhosting requirements

===Known Problems===
* Crashes are observed on macOS with Blender 4.2 and Blender 4.3. Related to window resizing and render completion. Unknown if Blender specific or also happening in standalone.
* Motion blur does not seem to work on "deeper iterations", e.g. copying an instanced object

LuxCoreRender Release Notes v2.10

2025-07-23T15:04:01Z

CodeHD: /* Bugfix release v2.10.1 */

__TOC__

=Bugfix release v2.10.1=

===LuxCore===
* Fixed a bug in luxcoreui (crash when loading a new .cfg file)
* Pin nvrtc dependency of pyluxcore to a specific version

===BlendLuxCore===
* Added a workaround for a Blender bug that throws an error when Blender is closed
* Added a linux development shell script (optional utility for developers)
* Viewport: Limit values in extremely overexposed areas, previously causing these areas to appear black

=LuxCore=

===New Features===

* New, multiplatform dependency manager: LuxCoreDeps. The new dep manager is based on Conan, an open source software which gives access to a database of thousands of build recipes, maintained up-to-date both by a company (JFrog) and a dynamic community. The deps are now built from sources, for a better control of build settings, binary compatibility etc.

* Dependencies updated to latest versions

* Buildability restored for all previous platforms: Linux, Windows, MacOS Intel

* Buildability added MacOS ARM platform.

* LuxCoreRender delivered in the form of Python wheels, published on PyPi.

* Automation (check, build, publish...) rewritten in Github Actions

===Fixed Bugs===

* LuxCore is now buildable again, on all previous platforms (Linux, Windows, MacOS Intel) + one (MacOS ARM).
* Crash fixed on tile path

===Known Problems===

= BlendLuxCore =

===New Features===
* Compatibility for Blender 4.2 and 4.3
* Partial compatibility for Blender 4.4 (not a release goal)
* Moved from Blenders addon system to the new extension system
* BlendLuxCore no longer bundles LuxCore binaries, platform specific binaries now distributed via PyPi
* Changed build pipeline from Azure to GitHub CI/CD
* Add square-root option to math node (alias to power 0.5)
* Add a setting to suppress LuxCore console log output
* Glass material now accepts IOR < 1
* Materials can now be individually excluded from material override
* BlendLuxCore specific menus are marked with an icon

===Fixed Bugs===
* Motion blur support for instances
* Improve custom normals export time by utilizing mesh.loops.foreach_get()
* LOL: Changed data access to adapt to new webhosting requirements

===Known Problems===
* Crashes are observed on macOS with Blender 4.2 and Blender 4.3. Related to window resizing and render completion. Unknown if Blender specific or also happening in standalone.
* Motion blur does not seem to work on "deeper iterations", e.g. copying an instanced object

BlendLuxCore FAQ

2025-07-21T08:33:11Z

CodeHD: Add "could not import pyluxcore" section

= Frequently Asked Questions =

=== When trying to use CUDA/OptiX, I get the error message: <code>RUNTIME ERROR: CUDA driver API error CUDA_ERROR_UNSUPPORTED_PTX_VERSION (code: 222, file:.../cuda.cpp, line: xxx): the provided PTX was compiled with an unsupported toolchain.</code> ===

Your nvidia driver is too old compared to nvidia runtime compiler used by LuxCore, so the code compiled by LuxCore runtime compiler cannot be run by your driver.

Please upgrade your nvidia driver to latest version, or at least to a suitable version with regard to runtime compiler: https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#id7

=== After installation, I get the error message "could not import pyluxcore" ===

"pyluxcore" is the binary core library. BlendLuxCore downloads and installs the correct version for your system during installation. This error indicates something went wrong with this installation. Possible solutions are:
* Check that online access is allowed in the Blender preferences.
* Download may be restricted in company networks. You can try an [https://wiki.luxcorerender.org/BlendLuxCore_Installation#Offline_Installation offline-installation].

=== I can not enable the BlendLuxCore addon, it shows errors ===

Most problems in this area stem from broken graphics driver installations. Try to re-install or update your graphics driver.

'''For Windows users:'''
* Make sure that you have installed the [https://www.microsoft.com/en-US/download/details.aspx?id=40784 Visual C++ Redistributable Packages for Visual Studio 2013]
* If you use v2.1alpha0 or later, you will also need:
** [https://aka.ms/vs/15/release/vc_redist.x64.exe Microsoft Visual C++ Redistributable for Visual Studio 2017]
** [https://software.intel.com/sites/default/files/managed/59/aa/ww_icl_redist_msi_2018.3.210.zip Intel C++ redistributable]

If this does not solve the problem, browse the [https://github.com/LuxCoreRender/BlendLuxCore/issues?q=is%3Aissue+label%3Ainstallation installation issues] in the bug tracker to check if your error message was already reported.
If it was not reported yet, open a new issue and copy the error message from the Blender console (on Windows, click Window -> Toggle System Console in Blender's menu. On Linux, start Blender from a terminal and try to enable the addon, then copy the error message from the terminal).

See the [[BlendLuxCore_Installation | installation page]] for information on how to install, update and remove the BlendLuxCore addon.

=== Is there something like Cycles' Layer Weight/Fresnel/Facing node in LuxCore? ===

No, in LuxCore there is no direct equivalent to this node, because it would not work with the many algorithms in LuxCore that trace rays from lights (instead of from the camera), like the bidirectional engine, light tracing mode, or the PhotonGI cache.

Of course, all materials in LuxCore are physically based and have realistic fresnel effects built-in.

You can achieve a similar effect with the dot product node, but it will work only for one viewpoint:

[[File:Layer_weight_for_one_direction.PNG | thumb | 400px | center]]

=== Can Cycles materials be used in BlendLuxCore? ===

To an extent, yes. Many common Cycles shader nodes can be used in BlendLuxCore:

* You can enable this individually for each material with the "Use Cycles Nodes" option in the material properties.
* You can also enable it for the whole scene at once with the "Use Cycles Settings" button in the render properties. This will configure all materials, lights and the world to use Cycles settings

Not all Cycles nodes and settings are supported. Here is an overview: https://github.com/LuxCoreRender/BlendLuxCore/issues/272

=== Can 2D/3D mapping be driven by textures in LuxCore? ===

In general, no, because it would lead to much worse performance on GPUs.

However, if you only need to drive the translation part of a texture mapping, since LuxCore v2.5 you can use the distort texture for this purpose:

[[File:Distort_texture.PNG | thumb | 400px | center | A checker texture (left) is distorted by a clouds texture (right). The result can be seen in the center]]

Texturing of rotation and scale is not yet possible.

=== What can be done against fireflies/hotpixels? ===

Sometimes, pixels appear that are much brighter than the surrounding pixels. Sometimes they are singular, sometimes clumped up. The underlying reason are light paths that are correct, but very hard to find with the current rendering algorithms, and thus they take much longer to render until noise-free than all other light paths in the image.

There are multiple ways to approach this problem:

* '''Try another rendering algorithm''', it might be able to find the firefly-causing light paths much easier than the one you currently use. For example, try going to the render properties, open the Light Paths panel and enable "Light Tracing", or try the [[PhotonGI | PhotonGI caustic cache]], or try using the bidirectional engine.
* You can '''clamp the brightness of all light paths''' to a maximum value, in the render properties, Light Paths panel, "Clamping" setting. BlendLuxCore can auto-detect a value for this setting that is in the right ballpark for your scene if you render once without clamping enabled, but often this value will not be the best, so you will need a bit of trial-and-error to find a good value. Note that the clamping value depends on the lighting in your scene, so there is no one universally good clamping value, and you might need to adjust it if you add a new light source to your scene that is brighter than the others. Using a clamping value that is too low will result in a low-contrast, washed-out image, while a too high value will leave fireflies unaffected.
* Try to find out which lights or materials are responsible for the fireflies. There might be small, hard-to-find light sources that are causing them. Or a specular material is reflecting such a light source. If you are willing to alter the look of the scene, you can make such a light source more visible/larger, or lower the specularity of such a material. You can also make some light sources invisble to indirect light rays, thus eliminating fireflies (light properties, "Visibility" panel). This can be a good idea for the sun, for example, if your scene contains lots of specular materials.

=== Why is my HDRI environment black and not showing up? ===
You probably have other very bright light sources in the scene, for example a sun or a sky lamp.

'''Solution:''' raise the gain value of the area or HDRI light source that is black. The gain value might need to be very high, e.g. 100000.

=== Why is my area lamp black? ===
See [[#"Why is my HDRI environment black and not showing up?"]]

=== When I change the brightness of my lamp, nothing happens ===

You are probably using an automatic tonemapper which adjusts itself to the changed brightness, making it seem like the brightness did not change.

'''Solution:''' Use a non-automatic tonemapper (camera settings -> [[ImagePipeline]]).


=== When I make one of my lights brighter, all the other lights get darker (or vice versa) ===

Similar to [[#"When I change the brightness of my lamp, nothing happens"]]. 
You are using an automatic tonemapper which tries to keep the image at the same brightness, making it seem like the brightness of the lamps changed.

'''Solution:''' Use a non-automatic tonemapper (camera settings -> [[ImagePipeline]]).


=== A material/object appears to be flickering when I move the camera and shows artifacts in final render ===

This effect is called [https://en.wikipedia.org/wiki/Z-fighting Z-fighting] and is usually caused by mesh faces being exactly on top of each other, e.g. two planes on the same world coordinates.

'''Solution:'''
* Check if there are two objects on top of each other, e.g. because you duplicated the object, cancelled the transform and forgot about it.
* Check if the mesh has duplicate faces. Enter edit mode and use the Remove Doubles button in the Tools panel, which might solve the problem in some cases.
Duplicate faces are often caused by extruding, cancelling the transform and forgetting about it.

=== There are dark triangular artifacts on my model, and I already checked for duplicate faces ===

Floating point numbers have a limited precision. When objects are very large (kilometers) or very small (micrometers), these precision issues become visible.

'''Solution:'''
* If the object has a "normal" size (something like 1 cm to 1 km), but was scaled up/down by a huge amount, try to apply the scale (Ctrl+A -> Scale). For example, this often happens with imported CAD models.
* If applying the scale did not help and your object has to be very small or large, consider to bring it into the normal scale mentioned above, and pretend that it has a larger/smaller size. For example, if you make a model of the solar system, you will just have to make the earth something like 12.742 m in diameter, and pretend that 1 m of your model is equal to 10^6 m.
* If both options above are not usable in your case, you can raise the minimum epsilon that LuxCore uses. This setting can be found in the scene properties, Units panel, after clicking "Advanced LuxCore Settings". By default, the minimum epsilon is 0.00001. Try to raise it to 0.0001 (multiply by 10) for a start and see if the artifacts disappear. Do not set this value higher than necessary, because it will cause all sorts of hard-to-track problems. Be especially careful if you are rendering a scene with volumes.

=== An object that I set to "smooth shading" looks like it is shaded flat in shadow penumbras ===

This artifact is called "terminator problem".

'''Solution:''' Unfortunately there is no real solution. You can only try to mitigate the effect by subdividing the geometry further and/or increase the size of the light source that is causing the problem.

=== How do I setup liquid in a glass container correctly? ===

This forum thread shows an example: https://forums.luxcorerender.org/viewtopic.php?f=4&t=728#p7550

=== Can I export my scene in LuxCore format to render it in LuxCore standalone? ===

Yes. In the render properties, LuxCore Tools panel, enable "FileSaver". Then render with F12.

=== How can I compile kernels from the command line? ===
Here is a way to compile kernels from the command line (out of Blender), for the latest version of pyluxcore:
<pre>
pip install pyluxcore --upgrade
python -c "import pyluxcore; pyluxcore.Init(); pyluxcore.KernelCacheFill()"
</pre>

= Getting Help =

If none of the above entries helped to solve your problem, consider asking in the [https://forums.luxcorerender.org/viewforum.php?f=4 user support forum] or [https://forums.luxcorerender.org/viewtopic.php?f=4&t=2 filing a bug report].

[[Category:BlendLuxCore]]

LuxCoreRender Release Notes v2.11

2025-07-02T10:19:43Z

CodeHD: /* BlendLuxCore */

= BlendLuxCore =

* Fresnel texture: "custom n,k" now accepts values > 1
* Change installation mechanism to use bpy.utils.extension_path_user() INCOMPLETE
* Include "OptiX" in addon settings label to avoid user questions about compatibility
* Added a workaround for a Blender bug that throws an error when Blender is closed
* Added a linux development shell script (optional utility for developers)
* Remove löeftover code from the Addons system that is no longer used with the Extensions system.

= LuxCore =
* Reduction of Boost footprint, replaced with standard equivalents available in C++20.
* For the need of previous point: replacement of apple-clang by clang 20 on MacOS platforms
* New target 'wheel-test' that builds a testing wheel in local build (<code>make wheel-test</code>)
* Requirement checking in <code>make deps</code>
* luxrays: rename GetConfigDir as GetCacheDir and use XDG_CACHE_HOME according to specifications (@illwieckz)
* Subdivision: add an "adaptive" setting to select between adaptive refinement and uniform refinement

= LuxCoreDeps =
* Dependencies updated to latest versions
* Removed a workaround introduced in previous version (we used to build a fake wheel to get containerization)
* OpenMP - MacOS: Use of homebrew OpenMP (up-to-date, compatible with clang 20) rather than Conan llvm-openmp (version 17...). As a consequence, for MacOS Intel, a version >= 13.0 is required.
* Opensubdiv: tbb activation. As a consequence, for MacOS Arm, a version >= 14.2 is required.
* OpenImageIO: deactivation of several image formats that seem unrelated to or unsupported by LuxCore: freetype, hdf5, ffmpeg, libheif, ptex, opencv, webp. This removal spares both compilation time and build result size. Those formats are reactivable, in case they were missing.
* OpenImageIO: To the contrary, activation of tbb option.

LuxCoreRender Release Notes v2.10

2025-07-02T10:15:26Z

CodeHD: Added section for bugfix release v2.10.1

__TOC__

=Bugfix release v2.10.1=

===LuxCore===
* Fixed a bug in luxcoreui (crash when loading a new .cfg file)
* Pin nvrtc dependency of pyluxcore to a specific version

===BlendLuxCore===
* Added a workaround for a Blender bug that throws an error when Blender is closed
* Added a linux development shell script (optional utility for developers)

=LuxCore=

===New Features===

* New, multiplatform dependency manager: LuxCoreDeps. The new dep manager is based on Conan, an open source software which gives access to a database of thousands of build recipes, maintained up-to-date both by a company (JFrog) and a dynamic community. The deps are now built from sources, for a better control of build settings, binary compatibility etc.

* Dependencies updated to latest versions

* Buildability restored for all previous platforms: Linux, Windows, MacOS Intel

* Buildability added MacOS ARM platform.

* LuxCoreRender delivered in the form of Python wheels, published on PyPi.

* Automation (check, build, publish...) rewritten in Github Actions

===Fixed Bugs===

* LuxCore is now buildable again, on all previous platforms (Linux, Windows, MacOS Intel) + one (MacOS ARM).
* Crash fixed on tile path

===Known Problems===

= BlendLuxCore =

===New Features===
* Compatibility for Blender 4.2 and 4.3
* Partial compatibility for Blender 4.4 (not a release goal)
* Moved from Blenders addon system to the new extension system
* BlendLuxCore no longer bundles LuxCore binaries, platform specific binaries now distributed via PyPi
* Changed build pipeline from Azure to GitHub CI/CD
* Add square-root option to math node (alias to power 0.5)
* Add a setting to suppress LuxCore console log output
* Glass material now accepts IOR < 1
* Materials can now be individually excluded from material override
* BlendLuxCore specific menus are marked with an icon

===Fixed Bugs===
* Motion blur support for instances
* Improve custom normals export time by utilizing mesh.loops.foreach_get()
* LOL: Changed data access to adapt to new webhosting requirements

===Known Problems===
* Crashes are observed on macOS with Blender 4.2 and Blender 4.3. Related to window resizing and render completion. Unknown if Blender specific or also happening in standalone.
* Motion blur does not seem to work on "deeper iterations", e.g. copying an instanced object

Developing and debugging BlendLuxCore

2025-06-12T11:47:25Z

CodeHD: /* Tips & Tricks */

= Introduction =

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.

These methods will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set BLC_DEV_PATH to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precendence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Utility shell script for launching Blender ==

The BlendLuxCore repository contains a shell script, called <code>blendev</code> (short for blender-development), located inside the <code>debug-helpers</code> subdirectory.
The purpose of this script is to easily launch Blender and switch between multiple versions of Blender, a regularly installed version of BlendLuxCore and pyluxcore, local development code of BlendLuxCore, and locally compiled versions of pyluxcore.
At the time of writing, this script is available only for linux/bash development.

Please see the <code>Readme.md</code> supplied alongside the script, and its internal help output <code>blendev -h</code> for detailed instructions on how to use it.

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

LuxCoreRender Wiki

2025-06-12T11:35:27Z

CodeHD: /* Documentation */

__NOTOC__
== Users ==

=== Documentation ===
* [[ BlendLuxCore_Installation | BlendLuxCore Installation]]
* [[ BlendLuxCore_FAQ | BlendLuxCore FAQ]]
* [[ LuxCoreRender_Tutorials | Tutorials ]]
* [[ LuxCoreRender_User%27s_Manual | LuxCoreRender User's Manual]]
* [[ :Category:BlendLuxCore | Blender Addon User's Manual ]]
* [[ PyLuxCoreTools | Command Line Tools ]]
* [[ LuxMark | LuxMark Benchmark]]

=== Useful links ===

* [https://luxcorerender.org/ ''LuxCoreRender Home Page'']
* [https://forums.luxcorerender.org/ ''LuxCoreRender Forums'']
* [[ External_Resources | External Resources ]]
* [[ Previous_Version | Previous Version (LuxRender) ]]

== Developers & Admins ==

=== Documentation ===

* [[ Building_LuxCoreRender | Building LuxCoreRender ]]
* [[ C++ Coding Guidelines ]]
* [[ Regular Maintenance Tasks ]]
* [[ Developing and debugging BlendLuxCore ]]
* [[ Compiling_LuxCore | Building LuxCoreRender (legacy) ]]
* [[ LuxCoreRender_Release_Notes | LuxCoreRender Release Notes ]]
* [[ LuxCore_API | LuxCore API ]]
* [[ LuxCore_API_Reference_Manual | LuxCore API Reference Manual]]
* [[ LuxCore_SDL_Reference_Manual | LuxCore SDL Reference Manual ]]

=== MaxToLux Documentation ===

* [[ MaxToLux_Plugin_Release_Notes | MaxToLux Plugin Release Notes]]
* [[ MaxToLux_Plugin_Reference_Manual | MaxToLux Plugin Reference Manual]]

=== Tutorials ===

* [[ Writing_an_Imagepipeline_Plugin | How to Write an Imagepipeline Plugin ]]
* [[ Implementing_a_Texture | How to Implement a Texture ]]

=== Information for Wiki Editors ===

We had to close the wiki registration because of too many spambots. 
If you want to contribute to the wiki, please request an account in our [https://forums.luxcorerender.org/viewforum.php?f=10 general discussion forum].

Consult the [//meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

LuxCoreRender Release Notes v2.11

2025-06-10T05:44:04Z

CodeHD: /* BlendLuxCore */

= BlendLuxCore =

* Fresnel texture: "custom n,k" now accepts values > 1

= LuxCore =
* Reduction of Boost footprint, replaced with standard equivalents available in C++20.
* For the need of previous point: replacement of apple-clang by clang 20 on MacOS platforms
* New target 'wheel-test' that builds a testing wheel in local build (<code>make wheel-test</code>)
* Requirement checking in <code>make deps</code>
* luxrays: rename GetConfigDir as GetCacheDir and use XDG_CACHE_HOME according to specifications (@illwieckz)
* Subdivision: add an "adaptive" setting to select between adaptive refinement and uniform refinement

= LuxCoreDeps =
* Dependencies updated to latest versions
* Removed a workaround introduced in previous version (we used to build a fake wheel to get containerization)
* OpenMP - MacOS: Use of homebrew OpenMP (up-to-date, compatible with clang 20) rather than Conan llvm-openmp (version 17...). As a consequence, for MacOS Intel, a version >= 13.0 is required.
* Opensubdiv: tbb activation. As a consequence, for MacOS Arm, a version >= 14.2 is required.
* OpenImageIO: deactivation of several image formats that seem unrelated to or unsupported by LuxCore: freetype, hdf5, ffmpeg, libheif, ptex, opencv, webp. This removal spares both compilation time and build result size. Those formats are reactivable, in case they were missing.
* OpenImageIO: To the contrary, activation of tbb option.

Developing and debugging BlendLuxCore

2025-06-09T18:28:21Z

CodeHD: /* Scenario #2: Working on pyluxcore */

= Introduction =

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.

These methods will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set BLC_DEV_PATH to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precendence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

As a verification, check for the following lines in the console output of Blender at startup: 
<code>[BLC] Installing local version of pyluxcore</code> --> A new local version will be installed. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed.</code> --> A local version was previously installed and is used again. 
<code>[BLC] installing pyluxcore version:</code> --> pyluxcore will be installed from PyPi. Replaces any previous installation. 
<code>[BLC] skipping pyluxcore installation. Specified version already installed.</code> --> A PyPi version was previously installed and is used again.

(Note: Further error messages exist but they are out of the scope of this article.)

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-06-09T18:23:19Z

CodeHD: /* Scenario #1: Working on BLC, using standard pyluxcore */

= Introduction =

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.

These methods will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set BLC_DEV_PATH to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

As a verification of this working correctly, the console output of Blender at startup will show the following line: 
<code>[BLC] USING LOCAL DEV VERSION OF BlendLuxCore</code>

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precendence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-06-09T18:20:51Z

CodeHD: /* Scenario #1: Working on BLC, using standard pyluxcore */

= Introduction =

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.

These methods will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

In the environment where you run Blender, and BlendLuxCore has already been installed using the normal installation method, set BLC_DEV_PATH to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>
For clarification, set this folder like you would set the systems <code>PATH</code> or <code>PYTHONPATH</code> variable, i.e. so that python can <code>import BlendLuxCore</code> from this location!

When this variable is set, all python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precendence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-06-09T18:17:31Z

CodeHD: Moving information to subsections

= Introduction =

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.

These methods will be explained in detail in the sections below.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

In the environment where you run Blender, set BLC_DEV_PATH to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>

Pack BLC, run Blender and install your packed version

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

When this variable is set, all python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

= Scenario #2: Working on pyluxcore =

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precendence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-06-09T18:15:34Z

CodeHD: /* Statement of problem */

= Introduction =

== Goal and audience ==
This document explains the approach to install a development version of BlendLuxCore (BLC) in Blender, so that it's possible to test and debug it. 
The targeted audience encompasses:
* BlendLuxCore development contributors
* BlendLuxCore advanced users/alpha testers who have been provided a dev version of BLC, in order to test a new feature.
* LuxCore developers who want to use Blender as a tool to test changes to the core engine.

== Statement of problem ==
BlendLuxCore (BLC) is composed of two parts:
* A Python module, essentially identical to the [https://github.com/LuxCoreRender/BlendLuxCore BlendLuxCore] repository.
* Underlying pyluxcore library, compiled from the [https://github.com/LuxCoreRender/LuxCore LuxCore] repository. Typically distributed as a Python wheel.

The python module is distributed as a zip-file, which is installed in Blender as an extension. During the installation process, the pyluxcore-wheel is downloaded from PyPi. During subsequent startup of Blender, the python script verifies the presence of pyluxcore and an additional (time-consuming) download is not necessary.

However, when developing BLC, we typically need to:
* Make Blender load a development version of the python module
* And optionally make BLC load a development version of the pyluxcore-wheel

The first goal can be achieved via an environment variable:
* <code>BLC_DEV_PATH</code>: path _folder containing_ the development repo of BlendLuxCore

When this variable is set, all python code from the development repo will be loaded, except the main <code>__init__.py</code> file. Changes to the latter may require a full reinstallation of BlendLuxCore, depending on what was changed.

For the second goal, two methods are available:
* Another environment variable, <code>BLC_WHEEL_PATH</code>: path to a development version of the wheel
* A subfolder <code>pyluxcore_custom/</code> within the installed python module. A development version of the wheel can be copied into this folder.
Note that the presence of a file inside <code>pyluxcore_custom/</code> will take precendence over the <code>BLC_WHEEL_PATH</code> variable!
To simplify further explanations, all explanations are presented in terms of the <code>BLC_WHEEL_PATH</code> variable.

When this variable is set, BLC computes a hash of the linked wheel. This hash is compared against information stored in the file <code>pyluxcore_installation_info.txt</code>, located within the installed python module. If the information matches, installation is skipped. Else, if it does not match, the local pyluxcore-wheel will be installed, replacing the previous version.
The text file also stores information if the previous installation was from PyPi or from a local wheel. This means, when the environment variable is unset after testing, it will again be replaced with the regular version from PyPi.

= Prerequisites =
In the next parts of the document, we shall assume:

You have set a development environment on your local computer with:
* a cloned repository of BlendLuxCore
* and optionally a cloned repository of LuxCore

You know how to "pack" BlendLuxCore, ie build an installable package of BLC:
<pre>
cmake -S . -B out -DCMAKE_BUILD_TYPE=Release
cmake --build out
</pre>

You know how to build a test wheel from LuxCore:
<pre>
make wheel-test
</pre>

= Scenario #1: Working on BLC, using standard pyluxcore =

In the environment where you run Blender, set BLC_DEV_PATH to the path of your dev repository:
<pre>export BLC_DEV_PATH=/path/to/folder/containing/BlendLuxCore</pre>

Pack BLC, run Blender and install your packed version

= Scenario #2: Working on pyluxcore =

<WORK IN PROGRESS>

= Tips & Tricks =

== Useful directories ==

The extension is installed in: 
<code>$HOME/.config/blender/<blender-version>/extensions/user_default</code>

The wheel is installed in: 
<code>$HOME/.config/blender/<blender version>/extensions/.local/lib/python<python-version>/site-packages</code>

== Wheel not loading - Python version mismatch between System and Blender ==

You may work in an environment where the version of the system-wide Python interpreter is different from that of Blender's embedded interpreter. This can happen, for instance, if your OS is ArchLinux. System-wide Python will be the latest version available (say, 3.13), whereas Blender interpreter will be an older one (for instance, 3.11).

If you build a test wheel without precaution, the tag will be the one of your system-wide Python and, when you try to install it in Blender, _the embedded interpreter will prevent you to do so (or will prevent you to import the lib)_.

The most simple workaround consists in using <code>pyenv</code> to set the right interpreter in your build session. Be careful to clear and reconfigure the whole project, afterwards: <pre>make clear && make deps</pre>

Once rebuilt, please check the version of pyluxcore in the build log:
<code>LuxCore/out/install/Debug/pyluxcore/pyluxcore.cpython-<version>-x86_64-linux-gnu.so</code>

<version> should match with the embedded interpreter.

Another point to be cautious about, in the present case: if pyluxcore is already installed system-wide, for a different version of Python than Blender, then Blender will fail installing the wheel. In this case, you'll have to uninstall your system-wide pyluxcore (<code>pip uninstall pyluxcore</code>) if you want Blender to install correctly.

== Message "[BLC] skipping pyluxcore installation. Custom wheel matching hash already installed." ==

If you think this message is irrelevant, clean the following file: <code>$HOME/.config/blender/4.2/extensions/.user/user_default/BlendLuxCore/pyluxcore_installation_info.txt</code>

== Debugging the wheel executing in Blender (Linux) ==

It is possible to debug the wheel when it is executed in Blender. To do so, follow the procedure below:
* Build the wheel in debug mode:
<pre>export LUX_BUILD_TYPE=Debug
make wheel-test</pre>

* Run Blender with gdb
<pre>gdb --args blender</pre>

(nota bene: check that the latest wheel is correctly installed by BlendLuxCore)

gdb should allow you to debug any call to LuxCore

Developing and debugging BlendLuxCore

2025-06-09T17:57:27Z

CodeHD: /* Goal and audience */

LuxCoreRender Release Notes v2.10

2025-05-09T07:50:57Z

CodeHD: BLC known problems

__TOC__

=LuxCore=

===New Features===

===Fixed Bugs===

===Known Problems===

= BlendLuxCore =

===New Features===
* Compatibility for Blender 4.2 and 4.3
* Partial compatibility for Blender 4.4 (not a release goal)
* Moved from Blenders addon system to the new extension system
* BlendLuxCore no longer bundles LuxCore binaries, platform specific binaries now distributed via PyPi
* Changed build pipeline from Azure to GitHub CI/CD
* Add square-root option to math node (alias to power 0.5)
* Add a setting to suppress LuxCore console log output
* Glass material now accepts IOR < 1
* Materials can now be individually excluded from material override
* BlendLuxCore specific menus are marked with an icon

===Fixed Bugs===
* Motion blur support for instances
* Improve custom normals export time by utilizing mesh.loops.foreach_get()
* LOL: Changed data access to adapt to new webhosting requirements

===Known Problems===
* Crashes are observed on macOS with Blender 4.2 and Blender 4.3. Related to window resizing and render completion. Unknown if Blender specific or also happening in standalone.
* Motion blur does not seem to work on "deeper iterations", e.g. copying an instanced object

BlendLuxCore Installation

2025-04-28T09:58:13Z

CodeHD: Update example files for offline installation.

__TOC__

Note: This version of the guide is valid as of Blender 4.2 LTS and BlendLuxCore v2.10. If you notice any incompatibilities with later versions, please inform the developers thorugh one of the community channels.

The guide to install legacy versions can be found on the page [[BlendLuxCore Installation (legacy)]] 

== Downloading ==

* Visit [https://luxcorerender.org/download/ the download page] to find the latest release versions.
* download the zip archive for one of the latest versions.
* Older versions of BlendLuxCore can be found on [https://github.com/LuxCoreRender/BlendLuxCore/releases the GitHub releases page].

== Installation ==

Follow the official Blender instructions for [https://docs.blender.org/manual/en/4.2/editors/preferences/extensions.html#get-extensions installing an extension]. Follow the steps for "Install from Disk":
* Open up the preferences menu: "Edit" -> "Preferences" (first picture)
* Go to the "Get Extensions" tab (second picture)
* Open the menu in the top right corner and select "Install from disk..." (second picture)
* Select the zip archive.
* After the installation, BlendLuxCore should automatically be activated. You can verify this in the "Add-ons" tab.
* It is recommended to restart Blender before using BlendLuxCore, to ensure all features are loaded correctly.

[[ File:Install-2.10-1.png | 372px ]]

[[ File:Install-2.10-2.png | 733px ]]

== How to Update ==

To update BlendLuxCore, you need to first uninstall the current version and then install the new version as outlined in section [[#Installation|Installation]].

To uninstall:
* Open up the preferences menu: "Edit" -> "Preferences".
* Go to the "Get Extensions" tab.
* Click on the arrow to the right of the BlendLuxCore item to open up the actions menu.
* Click on "Uninstall".

== Testing Experimental Versions ==

If you want to follow the latest development status, support development by testing new features, or you need an urgent bug-fix, then a few steps are necessary to use the latest versions.

What is important to understand in this context is the separation between "BlendLuxCore" and "LuxCore":
* LuxCore is the core library, written in C++, and distributed as "pyluxcore".
* BlendLuxCore is the interface between Blender and pyluxcore, written in python.
* The regular releases of BlendLuxCore will automatically download a specific, fixed version of pyluxcore.
* There is no automatic updating of either BlendLuxCore or pyluxcore, so that stability for production is not compromised.
* When using "latest" builds, both have to be installed separately

For the latest version of BlendLuxCore:
* download the [https://github.com/LuxCoreRender/BlendLuxCore/releases/tag/latest "Latest"] release in GitHub and install it following the instructions in [[#How_to_Update|How to Update]] and [[#Installation|Installation]].
* Note: This version will still install a (pre-configured) official release of pyluxcore, NOT its latest build.

To also get the latest version of pyluxcore:
* You will need an account on GitHub and log in.
* Go to the [https://github.com/LuxCoreRender/LuxCore/actions Actions] page of the LuxCore repository.
* Click on the latest workflow run. If you are in doubt which one is suitable, please ask in one of the support or community channels.
* At the bottom of the page, you find the "Artifacts" section.
* Download the correct file for your operating system and the python version used by your Blender version. The python (minor-)version is indicated by the last number of the file name
** Example: "cibw-wheels-windows-latest-11" is for Windows and python 3.11 --> Python 3.11 is the version you need for Blender 4.X
* Unpack the zip-file you downloaded to get a .whl-file
* This file needs to be placed in a subfolder pyluxcore_custom/ inside the BlendLuxCore extension folder
** On Windows: C:\Users\USERNAME\Appdata\Roaming\Blender Foundation\Blender\BLENDER_VERSION\extensions\user_default\BlendLuxCore\pyluxcore_custom\
** On Linux: /home/USERNAME/.config/blender/BLENDER_VERSION/extensions/user_default/BlendLuxCore/pyluxcore_custom/
** on macOS: /Users/USERNAME/Library/Application Support/Blender/BLENDER_VERSION/extensions/user_default/BlendLuxCore/pyluxcore_custom/
* Note: there must only be one .whl file in the pyluxcore_custom/ folder at any time!
* When you empty the pyluxcore_custom/ folder, the pre-defined release version will be installed again.

== Offline Installation ==

It is possible to install BlendLuxCore wihtout internet access, or in an environment where the regular installation method is blocked for network security reasons (i.e. some company networks).

In addition to the BlendLuxCore zip-file itself (see [[#Downloading | Downloading]]), you need to have the python-wheel of pyluxcore, and any further python-wheels that are dependencies, in the a appropriate version for your platform.

Example: For BlendLuxCore v2.10.0-rc.1, these will be:
* pyluxcore-2.10.0
* numpy-2.2.5
* nvidia_cuda_nvrtc_cu12-12.8.93

Example part 2: For Windows, you are looking for download links like the following:

[https://files.pythonhosted.org/packages/21/5b/76599c040e0873dd14885850f0e35d1d314f8abdf01200ebeb0b75422161/pyluxcore-2.10.0-cp311-cp311-win_amd64.whl pyluxcore]

[https://files.pythonhosted.org/packages/98/89/0c93baaf0094bdaaaa0536fe61a27b1dce8a505fa262a865ec142208cfe9/numpy-2.2.5-cp311-cp311-win_amd64.whl numpy]

[https://files.pythonhosted.org/packages/45/51/52a3d84baa2136cc8df15500ad731d74d3a1114d4c123e043cb608d4a32b/nvidia_cuda_nvrtc_cu12-12.8.93-py3-none-win_amd64.whl nvidia-cuda-nvrtc]

You can search and download these manually from [https://pypi.org PyPi], or copy them from another computer where the installation was successful. In the latter case, you should find the files in the wheels/ subdirectory of the extension installaton path (see [[#Testing_Experimental_Versions | Testing Experimental Versions]]).

Once you have obtained the files, follow these steps:
* Install the addon as described in [[#Installation | Installation]]. This will fail to import pyluxcore, as expected, but create the extensions directory required for the next steps. In Blender, the BlendLuxCore addon will be shown as installed, but disabled.
* Close Blender.
* Create a subdirectoy install_offline/ in the extension folder.
* Place the python-wheels in the install_offline/ subdirectory.
* Open Blender.
* Open the preferences menu, go to the Add-Ons tab.
* Activate BlendLuxCore by clicking the checkbox next to the BlendLuxCore item (see image).
* pyluxcore should now be installed. The install_offline/ directory will be deleted automatically if the installation was successful.
* Close and reopen Blender, and select LuxCoreRender as the rendering engine to verify that everythig works correctly.

[[ File:BlendLuxCore_activate.png | 786px ]]

== Common Problems and Errors ==

Some fixes for common problems are listed in the [https://wiki.luxcorerender.org/BlendLuxCore_FAQ#I_can_not_enable_the_BlendLuxCore_addon.2C_it_shows_errors FAQ].

[[Category:BlendLuxCore]]

Talk:Building LuxCoreRender

2025-04-25T22:36:50Z

CodeHD: Continuation of external discussion

__NOTOC__

== Workflow types ==
I did not sufficiently clarify my previous reasoning why '''Developer Workflows''' should come before '''Publisher workflows'''. Referencing to an unnamed statement in the introruction was insufficient on my side.

My point was the typical order of execution: First, you do development, then you publish. Therefore, I would have placed development first.

I do see your final line under the '''Workflow types''' section, now referencing this in an opposite logic.

== Minor suggestions ==
* Publisher Workflows -> Prerequisites: Mention the use of a local fork already at this point.

* use '''bold''' formatting instead of only ''cursive'' for more obvious emphasis in important locations. Without concrete suggestions right now which are particularly important.

* Change the phrase "'''magic''' words"