Import into Blender

Enable the MHX2 importer

Before the MHX2 importer can be used, it must be enabled in Blender. Choose File > User Preferences to open the Blender User Preferences window. In the Addon tab, select the MakeHuman category. Provided that you have copied or linked the import_runtime_mhx2 folder to Blender’s addon directory, it should be found here.


Enable the MHX2 importer by clicking in the checkbox in the upper-right corner, next to the running man icon. If you wish to enable the MHX2 importer every time you initialize Blender, press the Save User Settings button at the bottom-left corner.


It is also recommended that Auto Run Python Scripts is enabled in the File tab. The MHX2 importer sets up drivers that don’t work unless python scripts are enabled.

Import without modifications

By default a character is imported exactly as is was exported from MakeHuman.


To import a MHX2 file, select File > Import > MakeHuman (.mhx2). The importer can also be invoked from the tools panel. From the MHX Setup penal in the MHX2 Runtime tab, press the Import MHX2 button.


Either way, a file selector is opened. The importer options are found at the bottom of the left-hand side. The only import option is called Override Exported Data. Leave it unchecked (this is the default), select the exported .mhx2 file, and press the Import MHX2 button.


The character is now imported and can be posed and rendered.

There are some things to notice. First, the character is rigged with the skeleton chosen in MakeHuman. In particular, the new official MakeHuman rig can be imported in this way.


Second, vertices masked by clothes are removed from the human mesh. Depending on what you want, this may or may not be the desired behaviour. In particular, it is not possible to change or remove clothes in Blender, because there is no body below.


Third, the alternative topology is imported. In the default mode, the character is imported into Blender exactly as it looked in MakeHuman, including the alternative topology.

Import with modifications

If it were only possible to import characters exactly in the same way as they were designed in MakeHuman, there would be little reason to introduce a new format; FBX and Collada can already achieve this. The true power of MHX2 is that the exported character can be modified on import.


Select the Override Exported Data checkbox. Several new import options appear. Leave all options at their default values and import the character. Jane Doe is loaded into the scene, but this time the mesh is not rigged, because the Add Rig checkbox in the Rigging section was no selected.

Let us now explore the import options.


If the Helper Geometry option is selected, the full MakeHuman mesh including helper geometry is imported; otherwise, only the body is included.
If the Offset option is selected, the mesh is displaced so the object location coincides with the ground joint helper halfway between the feet; otherwise, the origin is placed at the center of mass in the pelvis area.


If the Add Rig option is enabled, more options become available in the Rigging section. The first  option allows us to choose the rig type. The default is Exported, i.e. the same rig that was created with Overwrite Exported Data disabled.


We can also use Import Human Type to control which human mesh is imported: Body (the MakeHuman base mesh), Proxy (the alternative topology), or Both. The viewport becomes a bit crowded, but we can see both the base mesh (Jane_doe:Body) and the proxy mesh (Jane_doe:Female1605) in the outliner.


Here the base mesh and the low-poly proxy have been moved to separate layers and the mask modifiers have been removed. If no alternative topology was selected when the character was exported from MakeHuman, the base mesh is always imported.


If the Rig Type is set to MHX, the character is instead rigged with the advanced MHX rig from MakeHuman 1.0. Note that when an MHX rig is selected, two more panels become visibible in the MHX2 tab: Layers and FK/IK Switch. The MHX rig will be described on another page.

If the Rig Type is set to Rigify, the character will be rigged with Rigify, which is Blender’s de-facto standard rig. For this to work, it is necessary that the Rigify add-on is enabled; it is found in the Rigging category. The MHX2 importer signals an error otherwise.


With a rigified rig is selected, various panels appear in the user interface panel to the right of the viewport. Those panels are controlled by Rigify and beyond the scope of the MHX2 importer.


Finally, there is a selection of straight-forward FK rigs for special target applications. The Custom Shapes option control the visible appearance of the bones.

Facial shapes and visemes

The MHX2 importer can add a set of facial shapekeys, analogous to those exported by MHX in MakeHuman alpha 6. Note that the face shapes are not yet final, but will be tweaked in the future.


To enable import with facial shapekeys, select the Face Shapes option. The body mesh becomes equipped with a large number of shapekeys, hopefully with self-explanatory names. The character’s expression can now be tweaked.


A character typically consists of several separate meshes (body, eyebrows, eyelashes, teeth, hair, clothes, etc.). Shapekeys are transferred from the body to all other relevant meshes. However, there is a problem: the shapekey values must be changed for each separate mesh. The picture above shows how the brows are raised on the body, but not on the eyebrows mesh.


To circumvent this problem, the shapekeys can be driven by armature properties. When the Face Shapes option is selected, the new option Face Drivers appears just below it. The Add Rig option must also be enabled, because the face shapes will be driven by armature properties.

When the character is imported with Face Shapes and Face Drivers, a new panel called ”Shapekeys” becomes visible in the MHX2 Runtime tab. The shapekey values of all meshes are now controlled simultaneously by the properties in this panel. The little pin icon to the right of the shape value pins that shape, i.e. set the value to one and the values of all other facial shapekeys to zero.

Controlling the shapekey value by rig properties is also valuable for file linking, because normally only the armature is proxified.


When Face Drivers is enabled, an additional panel called ”Visemes” also becomes visible. When the button for a certain viseme is pressed, the mouth area forms the corresponding sound. Only the mouth area is affected, i.e. shapekeys beginning with ”mouth”, ”lips” or ”tongue”. Other shapekeys such as the eyebrows are unchanged.

The Visemes panel consists of two more buttons:

  • Load Moho. Loads an animation in the Moho (.dat) format. A free application that generates Moho files is Papagayo.
  • Delete Lipsync. Remove all keyframes from the ”mouth”, ”lips” or ”tongue” properties.


It may be unintuitive to drive the face shape values from a long list of armature properties. A more user-friendly alternative is to use bones arranged around a bone with a special custom shape. This was the way face shapes were controlled back in MakeHuman alpha 6.

When the Face Shapes and Add Rig options are selected, the Face Panel option appears in the Rigging section. The face representation is added when with option is selected. Note that Face Drivers and Face Panel are mutually exclusive. The character’s expression can now be controlled by moving the face bones.


The viseme buttons work with the face panel as well. The buttons move the bones in the face representation, which in turn drive the face shapekeys of all meshes. This works with file linking as well.

Masking and visibility


Just as with the default unmodified import, the modified import also hides vertices under clothes. However, unlike the unmodified import, the hidden vertices are not destructively removed. Instead, for each piece of clothing covering part of the body, the body mesh has a mask modifier.


Visibility of the body mesh can be toggled on and off in the mask modifiers. The camera button affects rendering, the eye button affects the viewport, and the cube-with-corners button affects edit mode.


Mesh visibility can be driven by rig properties. There are two reasons for doing so:

  • The visibility properties control both the viewport and render visibility, and also whether mask modifiers of the other meshes are active in the viewport and in rendered. A single property controls four options.
  • Rig properties are still available with file linking. This means that a character can be defined with multiple clothes in a single blend file, and use different clothes in difference scenes, or perhaps no clothes at all.

Visibility drivers are added after the character has been imported into Blender. With the rig selected, press Add Visibility Drivers in the MHX Setup panel. This adds visibility drivers to every mesh that is a child of the rig. Note that if extra meshes are added to the character in Blender, they will also have visibility drivers.


After visibility drivers have been added, a new panel called ”Visibility” appears in the MHX2 Runtime tab. There the visibility of every mesh can be toggle on and off with the rig selected. When the visibility of the suit is turned off, so is the corresponding mask modifier, and the whole body is visible.

Merging and genitalia

The MHX2 importer can add genitals to the character. If the character was already exported with genitalia from MakeHuman, it is replaced by the added genital. The main reason to replace the standard MakeHuman genitalia is that the MHX2 version is snapped to the body mesh. If the hidden body vertices are removed and the body and genital meshes are merged, the genital is seamlessly joined with the body.


To add genitalia, press the Male or Female button in the importer. In this case the female genital is added.
After visibility drivers have been added and the suit has been hidden, we see how the body and vulva meshes match at the boundary.


The MHX2 importer can join the different meshes that constitute the character into a single mesh. Any mesh modifiers corresponding to joined meshes are applied to make sure that hidden vertices are really deleted.
The options that control this are found in the Merging section.

  • Merge Body Parts. When selected, some imported meshes are joined with the body. Exactly which meshes depends on the value of Maximum Merge Type.
  • Merge To Proxy. When this option is selected and a proxy mesh (a different topology) is being exported from MakeHuman, the body parts are joined with the proxy mesh instead of the body mesh.
  • Maximum Merge Type. Determines which types of meshes are joined with the body:
    • Body. Meshes that naturally are part of the body are joined with it: eyebrows, eyelashes, teeth, tongue, genitalia.
    • Hair. The meshes above plus any hair mesh is joined with the body.
    • Clothes. All imported meshes are joined with the body. This is mainly useful if the character will be exported to other applications, where mask modifiers are not available.

In the picture above, female genitalia has been added, and the body parts have been merged with the body. Note that there are only three meshes whose visibility is controlled by rig properties: the body, the hair, and the suit. All other meshes have been joined with the body. Note also that the boundary of the female genital is not only snapped to body vertices, but duplicate vertices have been merge, making the genital seamlessly integrated with the body mesh.


Warning: Merging genitals to a proxy mesh is in general a bad idea. The genitals have been designed to integrate seamlessly with the base mesh. This will not work with a different topology.


Finally, the picture above shows the result of merging all meshes, by setting the Maximum Merge Type to Clothes.


MakeHuman exports polygon hair. Although this can produce excellent results, some people prefer to use particle hair, e.g. because it is easier to animate. The MHX2 importer can replace the polygon hair in the MHX2 file with particle hair.

Hair import is controlled in the Hair section of the importer:

  • Hair. This is a drop-down list of available hairstyles. Currently only a single hairstyle is available, and the quality is not so good. More and better alternatives should be available in the future.
  • Hair On Proxy. Assign the hair to the alternative topology rather than to the base mesh. If not proxy has been loaded, the base mesh is nevertheless used.
  • Add Deflector. Add a low-poly deflector mesh to prevent the hair to penetrate the body mesh during simulations


If Hair has been selected, the importer ends in Particle Edit mode with the human mesh selected. The reason is that Blender’s particle system is quite brittle. Before finilizing import by changing to Object mode, verify that the Free Edit and Disconnect Hair buttons appear in the particle systems context. This is very important, because otherwise the hair will probably give you unpleasant surprises.


Jane Doe is now equipped with particle hair, and her exported polygon hair has been ignored.


If a proxy mesh has been imported and Hair On Proxy is selected, the hair is assigned to the proxy mesh instead. In this case MHX2 import stops in particle edit mode with the proxy mesh selected.


If Add Deflector is enabled, a low-poly deflector mesh is added to act as a collision object; the body mesh itself should not be used as a collision object, because the high poly-count makes simulations slow. Unfortunately, it appears that Blender’s hair simulation ignores collision object, so the deflector is rather useless at the moment. Hopefully Blender’s hair system will be improved in the future.


43 kommentarer till Import into Blender

  1. Rob skriver:

    >”Unfortunately, it appears that Blender’s hair simulation ignores collision object, so the deflector is rather useless at the moment. Hopefully Blender’s hair system will be improved in the future.”

    The Blender docs seem to suggest that a collison object could be of some use if you animate as soft body objects: ”Hair particles ignore deflecting objects (but you can animate them as softbodies which take deflection into account).” see


  2. Rob skriver:

    Hint: You should choose your final render engine in Blender BEFORE doing the .mhx2 import step. The advantage is that the importer will translate materials into Cycles nodes if the render engine is set to cycles at .mhx2 import time, but it will translate them into Blender internal render materials otherwise. (I don’t know how it handles game engine but I’m guessing BI)

    Gillad av 1 person

  3. wb skriver:

    You have a bit of a Freudian slip going on. I think you meant panel… otherwise not sure where the ”MHX Setup penal” might be in Blender 😉


  4. frost skriver:

    Can’t get makehuman Blender tools to work in OS X 10 or Windows 7. Makehuman board admin email address for registration confirmation is disabled, so I can’t put the question there… May I ask a question here?


    • thomasmakehuman skriver:

      They work for me, and I’m using Blender 2.73 on Win 7. Maybe you didn’t copy the files to the right directory. There is a list where to put Blender add-ons somewhere in the MH documentation, as well as in the Blender docs.

      Perhaps you are using a too old (or too new) version of Blender. They occasionally change the format of the file header that is necessary for Blender to recognize add-ons. MHX2 has been tested with Blender 2.70-2.73.


  5. Ariana Alexander skriver:

    Hello! I was wondering if there was some doucmentation somewhere for exporting the model from Blender and into Unreal Engine 4. I would like to be able to apply motion capture animation to the rig I made in MakeHuman and use the face shapes that come with it as morph targets for facial animation in the Engine. So far, my attempts to export an FBX from the MHX2 import has only resulted in crashing the Engine.


  6. Stephen skriver:

    I used the overwritten MHX2’s female_half_long hair. I did not merge the hair with a mesh. I went into object mode and scaled down the entire model by .1 on all axis. This was necessary to scale the model to a real world scale, which also makes this model match in Blender the dimensions it has in MakeHuman. This scaling made the hair look like an Afro.

    I also tried merging the hair with the base mesh. The result was the same.

    With hair selected in the Outliner I went to Particle context in Properties and found that the hair was assigned to the Skull vertex group. I selected Skull in edit mode to find out which vertices were assigned to Skull. I expected many vertices on the scalp would be selected because this is how I had done hair before. What I found instead is a single vertex assigned to Skull. This was on the model’s left side high inside the mouth.

    Do you have documentation about how your hair works? I do not know what to do with this. Right now it looks to me like I will have to make my own hair the same way I have done it before, starting with selecting all the vertices on the scalp where hair is to originate from.

    My ultimate goal is to make your hair obey gravity in physics simulations.


  7. jtsmith skriver:

    Using current nightly build of MH (1.1) and just downloaded your .26 version and using Blender version 2.74. When importing my .mxh2 into blender, if there are any additional meshes, like basic hair, eyes, and even clothes that were exported from MH then the ”extra” meshes are extremely small and centered inside the body mesh (yet the masks still cover the body appropriately.) This only happens when selecting to ”Override Exported Data”, if it is unchecked then the meshes are where they are suppose to be however this does no good if I need any of the other import options such as a rig. I have tried all different combinations when importing but all have the same result, less leaving Override turned off. Any suggestions or perhaps I’m doing something wrong? I have gone through these docs several times search for something I may have mis-set but can’t find anything. Thanks for your help!


    • thomasmakehuman skriver:

      Evidently I didn’t test this version before releasing it as a stable. The bug should now be fixed, both on bitbucket and the stable v 0.26. The download link for the fixed stable version is the same as before.


      • jtsmith skriver:

        Awesome, thanks for the quick reply and hotfix! I am experiencing a new problem now, though to be fair I occasionally got this error prior to hotfix, but now I seem to get it every time. See image/error here:

        The mesh I export does not get imported and as you can see from the image, it’s a blank/generic mesh with the helpers. I leave all the import settings to default, except adding a rig (all produce same results.) The rig from MH is just a basic mesh for testing, adding only clothes, changing height and gender. I’ve tried to import with a few different settings but all produce same result/error.

        Thanks again for all your hard work, Sir!


      • thomasmakehuman skriver:

        The problem was caused by the shoes, which carry their own vertex groups. Should be fixed now, both in unstable and v 0.26


      • jtsmith skriver:

        Thank you Sir! I, as I’m sure many others, are very grateful for the work you do and have done to make our lives easier and more enjoyable! You are awesome, keep up the great work!


  8. bug skriver:

    My exported file are in mhx format and whenb importing in blender no such override option comes…..


  9. thios skriver:

    Great job with the importer! Is there a way, automated or not, to convert the visemes into shapekeys, like the old ”generate visemes” button used to do?


  10. Great work! Is there a way to edit the visemes? My AH and OOO shapes are a little too extreme and I’d love to modify them


    • thomasmakehuman skriver:

      Not really. The visemes are defined in the .mxa files in import_runtime_mhx2/data/hm8/faceshapes. They were created as MH targets and can be edited in MakeTarget; these target files are located in the raw subdirectory. However, the targets were then split up into Left/Right and sometimes Upper Lip/Lower Lip parts with a python script that is not included in the MHX repo.


  11. Talisman Skulls skriver:

    I want to know how to import Into MakeHuman from Blender! Mhx can export too blender. you can make MH into a dae, or whatever, Fine, I want to know how to sent it Back In!


  12. dlprentice skriver:

    I just wanted to take a moment and thank you. This guide was useful to me.


  13. Alek skriver:

    Great work Thomas!
    Right now your export isn’t part of official distribution of MakeHuman and models exported with your addon cannot be used with CC0 license. Is there any problem to include it in official version?

    cheers, Alek


    • thomasmakehuman skriver:

      Yes, there are two problems: I will definitely not allow it, and I don’t think that the MH team would allow it either. We disagreed about who made decisions about the old mhx format, and there is no way I’m going to give up any control over mhx2.


      • Fatty Wompus skriver:

        First let me say thank you for some awesome plugins and your generosity in providing them freely to the world. That being said I find your unwillingness to relinquish control of MHX2 completely understandable. But would you consider at least officially granting CCo license or at least GNU GPL for any Export or Output data derived from your plugin? I don’t know you personally but it seems you are concerned with control of your format more than suing people for using models produced with your plugins in commercial games. I would assume this is the case and not worry about it since any artwork created with Blender or any any ”Export” from Makehuman (the two programs your plugins are designed to work with) is able to be used in such a way. Although this has sparked some research on my part and it seems, on top of different licensing, a big difference between those two programs is original artwork created with Blender could have some traditional copy protection as it could actually be original artwork in some cases. But the output of Makehuman is essentially a conglomeration of Makehuman’s assets adjusted with sliders so it wouldn’t be inconceivable for multiple people reproduce the same result fairly easily. As a hopeful indy game developer I’m sure I’m not alone in saying I’m more concerned with how excellent these programs and plugins are and the wonderful models they allow me to create, than having any concern for someone one day trying to copy a model from something I made. But back to the licensing issue… I am not a lawyer but the AGPL license does sound like if there is any trace of anything even remotely associated with the AGPL license in my game then my game would inherit the AGPL license and I would be required to make source code available. I may be over reacting and models created could be some kind of ”fair use” vs. me trying to fork your plugin. Alek’s seeming immediate dismissal of using it compounded by my reading about most corporations not going near anything AGPL just got me worrying. So any response form you the creator would be much appreciated. Sorry for the long winded post. And thank you again for a wonderful set of plugins.


      • thomasmakehuman skriver:

        Added a page with a license statement. Any extra content added by the MHX2 importer is released under CC0, to the extent that the content is mine (there is a hair which is relased under a different CC license, because that is what the original creator stated). Content exported from MH maintains its original license, at least as far as I am concerned.


      • Fatty Wompus skriver:

        Excellent! Thank you for the fast reply and for clearing that up in such an unexpectedly detailed manner 🙂


  14. Alek skriver:

    It’s not the best news I’ve heard. But it is good to know that on the early stage of my project. Thank you for your answer anyway.


  15. Phil skriver:

    I’m confused as to why anyone would go to this trouble. Is 3D really so fun as to merit all this bother? Wouldn’t be easier to build your own Space Shuttle?


  16. Luiza skriver:

    Hi Thomas,

    I have created a Makehuman character and imported it with mhx2 add-on for Blender (v2.77). I have created a lip-synching animation with QuickTalk add-on ( The add-on uses Makehuman Visemes drivers. Everything works fine in the Blender Renderer, but I am having trouble using these animations within Blender Game Engine.
    The animation doesn’t play in BGE Standalone Player and I have no error/warning messages on the console. Are there any known issues with the Visemes in BGE? I would really appreciate your help!


  17. Luiza Mici skriver:

    Hi Thomas,

    I have a question about the Visemes: I have created a Makehuman character and imported it with mhx2 format into Blender (v2.77). I have created a lip-synching animation with QuickTalk add-on (, which offers the option to use Makehuman Visemes drivers. Everything is perfect in Blender Render, but the animation doesn’t play at all in Blender Game Engine. Are there any know issues with the Visemes in Blender Game Engine? I would really appreciate your help!


  18. Alexander skriver:

    Hey, I have a problem which occured during my first import of a mhx2-file into Blender (2.66).
    It says:

    TypeError: error with keyboard argument ”type” – enum ”ShaderNodeTexCoord” not found in (‘OUTPUT’, ‘MATERIAL’, ‘RGB’, ‘VALUE’, ‘MIX RGB’, ‘VALTORGB’…location: <unknown location<:-1

    What to do?


    • thomasmakehuman skriver:

      Blender 2.66 was a veery long time ago. The first version of the mhx2 importer was developed for Blender 2.70, and we are at 2.78 by now. The python API has probably changed since 2.66. Please consider upgrading to a more recent version of Blender.


  19. Margaret Toigo skriver:

    I just want to thank you for this excellent software that makes MakeHuman useful for actual projects. And your MakeClothes and MakeWalk tools are very cool and rather addictive.


  20. Terry Havard II skriver:

    What if it is in a .mhm format?


  21. Robin skriver:

    thank you for this awesome software!
    I have a question regarding shape keys: Do I understand correctly that there are only shape keys for the face and none for other parts of the body? Is there any way of exporting shape keys for the vertices around the elbow, hips and knees from makehuman? I have been trying for a while to create realistic shape keys in blender but the result always looks off.
    Im thankful for any answer.

    Gillad av 1 person

    • thomasmakehuman skriver:

      There is no simple way that I know of. The facial morphs in mhx2 are not part of MH but added by the MHX2 importer.


      • Robin skriver:

        thank you for your answer! you dont happen to know where i can find an blender file of a makehuman model with shape keys for other parts of the body? I need to see how its done correctly to get really anatomically correct poses.
        again: thank you very much for your software and support. People like you are the reason I love the open source community.


  22. rknop skriver:

    I cannot for the life of me find this ”Override Exported Data” checkbox.
    I’ve got 0.28 of the tools installed. I’ve got auto-run python scripts enabled. There is an ”Import MHX2” button on the ”MHX2 Runtime” tab but that’s it. No checkbox for overriding exported data. When I import, a lot of the options thereafter are greyed out.
    Is there something else one needs to do in order to make this functionality available/


    • rknop skriver:

      (Facpalm.) OK, found it. I kept expecting it to be in the ”T” panel of the 3d window, underneath the ”Import MHX2” button. No, all of that stuff is in the left pane of the file selection window….
      Sorry about the dumb question.


  23. Roberto Collins skriver:

    Hi Thomas
    Cannot see the Override Exported Data check box, MHX Setup
    Makehuman Import Runtime v 0.27. Blender 278c
    Please help



Fyll i dina uppgifter nedan eller klicka på en ikon för att logga in:

Du kommenterar med ditt Logga ut /  Ändra )


Du kommenterar med ditt Twitter-konto. Logga ut /  Ändra )


Du kommenterar med ditt Facebook-konto. Logga ut /  Ändra )

Ansluter till %s