Houdini 18.5 HQueue


How to set up a basic HQueue farm.

On this page

Before you begin


This guide assumes the server and client machines all share the same operating system (Linux, macOS, or Windows). It is possible to set up an HQueue farm with mixed operating systems, but that is not covered in this quick guide.

The following items are required before setting up an HQueue farm:

Network connectivity

  • Machines must be able to "see" or ping each other by their domain (DNS) names or by their IP addresseses.

  • Client machines must be able to connect to the server machine through port 5000. The server machine must be able to connect to client machines through port 5001. This may require opening ports in any local firewalls.

Shared network folder

  • The servers and clients must be able to access a shared network filesystem, for example an NFS mount of SMB share.

  • The shared folder must be mounted at the same location on every machine, for example /nfs/storage/ on Linux, or \\bigdisk\hq on Windows.


  • Install Houdini on every client machine in the same install directory.


    On macOS, the default Houdini installation path is /Applications/Houdini/HoudiniX.Y.ZZZ.


    On Windows, the default Houdini installation path is C:/Program Files/Side Effects Software/Houdini X.Y.ZZZ.


    On Linux, the default Houdini installation path is /opt/hfsX.Y.ZZZ.

  • Houdini licensing must be set up correctly on each client machine as well, so the client software can launch licensed executables such as hython and mantra.

Installing HQueue

Testing the Farm

To test that the HQueue farm is configured correctly you can submit a simple Houdini render job.

Here’s how:

  1. Launch Houdini.

  2. Create a simple scene. At a minimum, put down some geometry, a light, a camera and a Mantra ROP for rendering.

  3. Navigate to the /out node network and put down an HQueue Render ROP.

  4. In the Parameters pane, set the Output Driver parameter to your Mantra ROP.

  5. Point the HQueue Server parameter to your HQueue farm. For example, http://serverMachine:5000.


    If DNS is not configured for serverMachine then you can alternatively use the server machine’s IP address in the URL. For example, http://X.X.X.X:5000.

  6. Then set Target HFS to where Houdini is installed on the client machines.


    For macOS, set Target HFS to:



    For Windows, set Target HFS to:

    C:/Program Files/Side Effects Software/Houdini X.Y.ZZZ


    For Linux, set Target HFS to:

  7. Save the .hip file somewhere in your network folder.


    On macOS, the network folder is defined by the hqserver.sharedNetwork.mount.macosx key in the HQueue Server configuration file. For example, save the .hip file to /Volumes/myShare/test.hip.


    On Windows, the network folder is defined by the hqserver.sharedNetwork.mount.windows key in the HQueue Server configuration file. For example, save the .hip file to X:/test.hip.


    On Linux, the network folder is defined by the hqserver.sharedNetwork.mount.linux key in the HQueue Server configuration file. For example, save the .hip file to /mnt/myShare/test.hip.

  8. Click Submit Job at the top of the Parameters pane.

    • A new job will appear in the HQueue web interface.

    • You can click on the job’s id to dive into the job and see more details.


When a job fails, you can find out why by clicking on the job’s id in the HQueue web interface. This will take you inside of the job where you can see more details. If any of the job’s Child Jobs failed then click on the child job’s id to further dive inside. Eventually you will see an Output Log field with the job’s output. The output will contain an error message indicating why the job failed.

Check out the Troubleshooting FAQs for information on common job failure errors and possible solutions.

Optional: hquser account

On client machines you can optionally set up an hquser user and hqgroup user group to run Hqueue as. By convention the user and group ID are both 601, and the user’s password is hqpass, but you can change these.


Your Linux distribution may come with a user interface for creating user accounts, otherwise use the adduser command.


You can create users and groups in the Users and Groups panel of System Preferences.

Having consistent user accounts across clients has benefits:

  • Don’t have to keep track of different user accounts on different machines when you need to log into a particular client.

  • All files created by the client software are owned by a single consistent user.

Once you have created the user and group, you should start the HQueue server/client as hquser.


Getting started

  • About HQueue

    HQueue is a general-purpose job management system. You can use it to distribute renders, simulations, and other work to remote clients.

  • Installation

    How to set up a basic HQueue farm.

  • Configuration

    How to set configuration options for the HQueue server and clients.

  • How to submit jobs

    How to put work on the farm.

Managing the farm

  • Managing clients

    How to use the web interface or local logins to add, remove, restart, and manage client machines.

  • Managing jobs

    How to view and manage jobs on the farm.

  • Managing client groups

    How to use the web interface or local logins to create and manage groups of client machines.

  • Notes

    Each client and job can have informational notes attached.

  • Resources

    You can specify what resources (such as licenses) are available on each client, so jobs can be scheduled on clients where they can run.

  • Network Folders

    How to use the Network Folder management page.

Next steps

  • Logging

    Hqueue stores separate logs for errors and scheduling events, and each client also generates a log.

  • Uninstalling

    How to uninstall the HQueue server or client software.

  • FAQs

    Answers to frequently asked questions.

Guru level

  • Remote API

    You can connect to the HQueue server over the network and call functions to manipulate and query jobs and other information.

  • Jobs specification details

    More detail on the internals of a job specification for users who want to submit custom jobs.

  • Switching to MySQL (Linux only)

    You can optionally configure HQueue to use MySQL instead of SQLite on Linux.