How to setup Django for an existing project


Is there an easy, built in way to do this, or do I need to manually copy the .iml file from a new project each time and change the settings?

How does IntelliJ not find Django when importing an existing project?

Also the documentation in the help is not clear on this at all and it's very frustrating.



Hi Craig,

Could you please clarify: do you try to open existing Django project in Intellij IDEA? If so, please go to `File| Project Structure| Facets| Press "+" for "Add"| Django` and specify the corresponding settings for your project. If it's not the case please provide more info about it.


I have a folder containing a Django project I cloned from github (for example).

In IntelliJ I open the folder containing the project.

I then use the `File| Project Structure` to create a new Virtual environment.

IntelliJ seems to find and load the dependencies listed in the requirements.txt file just fine into the virtual environment (Django being one of those).

I then want to set this as a Django project so I can debug it.

I try as you suggest, but the`File| Project Structure| Facets| Press "+" for "Add"| Django` option is not there.

My work around is to copy and edit a `django.iml` from a blank project I setup, but this to me seems like it's the result of a bug that cannot properly detect the Django project, or something else is blocking me from being able to add that Facet. 

How do I make the facet show up? Is there a way around having to copy and edit the `.iml` file for each of these projects?

Thank you.


Any update on how to get this facet to show up?

I have completely reinstalled the latest IntelliJ from scratch.

I installed defaults plus python plugin.

I open up the project using the folder open, it detects python. I click configure in alert box, it opens a window listed X number python files, I click ok.

Next I go to project settings. I select a New... then select Python SDK, then Add Local, I select a local virtual environment (created by virtualenv), it has Django installed, I click apply.

I then go to the Facets page, Python is listed, I click the + button, I get and error "No suitable Modules for Python facet found"

I then try to go to Modules page as listed in the Help documentation, Python is listed. I click the + button, I have 2 options: New Module, Import Module. The Django Module is not listed.

How do I tell IntelliJ that this project uses Django? How can I debug as Django project if I am not able to do this?

I find this workflow flawed and VERY frustrating.

Please help. Thank you.


After fighting with this for some more hours (yes, hours!!!), I find that if I do an "import project" (instead of using the folder opening the folder), I can get it to recognize the Django project, however, there are NO debug settings. If I try and create a configuration, I'm left with the message (which holds no bearing since there in no "Settings->Django Support" option anywhere in IntelliJ):

No file specified in Settings->Django Support
/home/craig/projects/django/venv/bin/python3.5 /home/craig/.IntelliJIdea2017.1/config/plugins/python/helpers/pydev/ --multiproc --qt-support --client --port 44719 --file /home/craig/projects/django/venv/bin/ runserver localhost:63212
pydev debugger: process 22095 is connecting

Connected to pydev debugger (build 171.4073.35)
Traceback (most recent call last):
File "/home/craig/.IntelliJIdea2017.1/config/plugins/python/helpers/pydev/", line 1578, in <module>
globals =['file'], None, None, is_module)
File "/home/craig/.IntelliJIdea2017.1/config/plugins/python/helpers/pydev/", line 1015, in run
pydev_imports.execfile(file, globals, locals) # execute the script
File "/home/craig/.IntelliJIdea2017.1/config/plugins/python/helpers/pydev/_pydev_imps/", line 18, in execfile
exec(compile(contents+"\n", file, 'exec'), glob, loc)
File "/home/craig/projects/django/venv/bin/", line 5, in <module>
File "/home/craig/projects/django/venv/lib/python3.5/site-packages/django/core/management/", line 363, in execute_from_command_line
File "/home/craig/projects/django/venv/lib/python3.5/site-packages/django/core/management/", line 307, in execute
File "/home/craig/projects/django/venv/lib/python3.5/site-packages/django/conf/", line 56, in __getattr__
File "/home/craig/projects/django/venv/lib/python3.5/site-packages/django/conf/", line 41, in _setup
self._wrapped = Settings(settings_module)
File "/home/craig/projects/django/venv/lib/python3.5/site-packages/django/conf/", line 110, in __init__
mod = importlib.import_module(self.SETTINGS_MODULE)
File "/home/craig/projects/django/venv/lib/python3.5/importlib/", line 126, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
File "<frozen importlib._bootstrap>", line 986, in _gcd_import
File "<frozen importlib._bootstrap>", line 969, in _find_and_load
File "<frozen importlib._bootstrap>", line 956, in _find_and_load_unlocked
ImportError: No module named 'settings'

When running Django from the command line, I do not get this error. As a paying user of several years, I find this to be a terrible user experience. When is this going to be fixed since I can find people having issues since at least 2013? This is a major for me. I've been spending way too much time fighting with this to just get it to do something it advertises it can do and the documentation is wrong and no help at all. How do I fix this? How do I get this work? What can I do? How can I elevate this issue with your engineers to actually have someone look into this?


Duplicate of support request in Zendesk.


Any updates? It's been an year. Still the problem is not fixed (Intellij UE 2017.3.5).


No, I still battle with this issue. This issue dates back further than a year, this was just my attempt to scream about it. Seems like nobody at Jetbrains has ever used IntelliJ with the pycharm plugin on a Django project that they downloaded from Github? Not sure how that works.

What I've found is that you can manually add a facet in order to force Intellij to think it's been setup already. Terrible answer (and user experience), I agree, and more of a work around than an answer but it seems to work pretty much every time. Maybe one day someone at Jetbrains will actually try and test this very common use case and realize how bad it really is and fix it. Until then, here are my steps:

  1. Setup your project using the File->New (from existing sources)
  2. Run though the wizard, (don't worry, it will not find Django as a framework, so that's expected).
  3. It may now find the Django framework (this happens occasionally) in which case, click the configure button in the popup (don't forget to go into your project settings and fix the location of, if not continue...
  4. Now open (or create) the .iml file in the project root (named after the project name you gave it in step 2 of the wizard, usually the directory name if just clicked next)
  5. Take the django_app.iml file (pasted below), and override the .iml contents with it.
  6. replace line 7 with the relative path ('django_app/') to your django file, as well as update any other paths appropriately. 
  7. Close and reopen your project, go to the project settings and you should now see the Django facet.
  8. You can now go to Run->Edit Configurations and add the Django server feature without issue.

Hope this helps. Good luck.


<?xml version="1.0" encoding="UTF-8"?>
<module type="PYTHON_MODULE" version="4">
<component name="FacetManager">
<facet type="django" name="Django">
<option name="rootFolder" value="$MODULE_DIR$" />
<option name="settingsModule" value="django_app/" />
<option name="manageScript" value="" />
<option name="environment" value="&lt;map/&gt;" />
<option name="doNotUseTestRunner" value="false" />
<component name="NewModuleRootManager" inherit-compiler-output="true">
<exclude-output />
<content url="file://$MODULE_DIR$" />
<orderEntry type="inheritedJdk" />
<orderEntry type="sourceFolder" forTests="false" />
<component name="TemplatesService">
<option name="TEMPLATE_CONFIGURATION" value="Django" />



Hey Craig,

Thanks for the detailed steps. It worked!... :)


Hi Craig & JetBrains,

I struggle with the same problem in my Evaluation copy of IntelliJ Ultimate. I before used PyCharm Community, and wanted to test the Ultimate version because using Js/Vue.js together with Django "should" be more convenient with Ultimate.


I struggled for hours now too, just to get existing Django projects working. They don't. I can't use pipenv, and it complains about not having a Django module. And I can't change it, because I can't add the "Django" facet to the project.

The ".iml injection method of Craig didn't help here neither."

AFAIK there is a "File|New|Module from existing sources..." Menu Item that fullfills that purpose - is that right? (Ultimate 2018.2)


Please fix this bug.


You'll need to use the ""File|New|Project from existing sources..." Do NOT use Module, I've found this is strictly for Java (remember that IntelliJ is first and foremost a Java IDE).

Hopefully that clarification will help, you can and then follow my steps above. 

To clarify some more, step 3 happens after the project has been created and loaded (meaning you've completed the project import wizard).

If this and the iml file don't work, I'm afraid this is beyond my help. You'll need someone at Jetbrains to actually look at this instead of just send you though the autotext loops. If you end up getting this into youtrack, please post the link to the issue here, I'll be sure to add my vote and my comments/work arounds.

I hope this helps you.



I had the same issue and this is what I did.


I created a brand new project called blank2 (NOT FROM SOURCE) with django framework support and the same python env/interpreter you would like to use on existing project. I then created an empty folder and copied 4 files


first is 'blank2.iml' found on the main blank project folder

then copied the 3 files found in the .idea folder;

misc.xml, workspace.xml, modules.xml 


open each file using a text editor, if on linux, gedit and search it for blank2. 

Any instances of blank2 should be changed to the name of your existing project

RENAME the blank2.iml file to be the name of your project.iml.  for example if name of your project is mysite then rename to mysite.iml

After this, paste the .iml file in the main existing project folder and the paste the xml files in the .idea folder.  If there is an existing .iml file in the .idea folder delete it. 


When this is done, you might get an error, just close and open the project. it might say something as could not open blah blah module and ask to delete  DO NOT DELETE. Once it prompts you and you refuse to delete a new .iml file will be created in .idea folder.

And everything should work (no need to go to project structure etc)



2018.3.5, This is still an issue. Tried setting up an existing Django project today and still had to deal with this.

It seems that the .iml file has been moved.
I could no longer get it working unless it was placed within the /.idea directory within the project. The Import seems to have become less functional for me as well, not picking up python or Django.

I've also found this link (, which says to use the File->New (not from existing sources) but then select the existing project source.


To shed a bit of light on this, it seems that the issue is that IntelliJ incorrectly thinks that EVERYTHING is a python facet, which is JAVA_MODULE, which is why you cannot add the Django facet, since that is a PYTHON_MODULE. IDK why the when python is detected it defaults to making the project a JAVA_MODULE first instead of default to a PYTHON_MODULE as I feel like this would then fix so many issues including this one.

I created a YouTrack ticket here:

Please go vote for this and add any additional info/comments.



Hi Craig,

Probably your ticket was deleted. I tried to thumbs up but I got 404.

About this whole problem which is impacting me too, I have something to add:

  • The solution described here is working for me. When you have a Django project, simply use import project for the first step and follow the wizard.
  • Run Task available at Tools won't work at first. You need to configure Django facet in your Project Structure. My case:

  • Now if you select Run Task available at Tools it will work accordingly.

  • Django Console won't work, forget it. You'll need to customize a script for Python Console in your starting script. Do not forget to set DJANGO_SETTINGS_MODULE to your settings module.

  • The entire script can be found here. Now you can fun with Django console at your will.

My setup: IntelliJ IDEA Ultimate 2018.3.5

Helpful links on StackOverflow:


Looks like they did.

Such great support they have for the price I pay (yep I paid for a license).

This also sucks when you work on multiple projects and you have to do this every single time. Just A TERRIBLE user experience.

Going to enter another support request, I'm tried of this, it's been 4+ years.



After a tweet and support request, the youtrack ticket it back!

Also, from support staff, there is no better solution at the moment unfortunately and no known time as to if or when this will get fixed, however the more votes on the ticket the more chance there is of it getting picked up and resolved.

Thanks all.


Wanted to upvote the ticket but it's gone again: - 404.


They moved this over to pyCharm support (since apparently, it's not the intelliJ people who support the plugins), so it seems that the ticket got a new ID and a new url (sorry I didn't realize this at first). Here's this ticket and a related ticket.




A coworker of mine, had a different way of getting IntelliJ to recognize Django and thus far, it's been working for me so thought I'd share. 

Assuming you have an existing Django project from git (or wherever).

Now, in IntelliJ, use the File > New > Project... Yes, new project. Not new from sources, just new.

In the dialog that opens, select Python on the left and you should see Django as an option. Select that, give it the name of the directory (usually from git clone) in the `Application Name` field and click next.

Skip the "create from template" screen, next

In the next screen, in the "project Name" enter the name of the project (again, this should match the directory of your code), click next

It will tell you that the directory is not empty and ask if you want to override it, click yes (don't worry, it's not going to override any of your files).

That's it! You have a django project in the most unintuitive way possible, but slightly better than editing a file I guess.

Good luck


I tried the XML edit above - well, manually merged it with my existing .iml to keep my project directories etc. I didn't have "JAVA_MODULE" so I didn't have to replace that. But it didn't work, and it said Django facet could not be found. Well turns out I really did need to add "PYTHON_MODULE" even though "JAVA_MODULE" was not there before.

So the edit was from

<module version="4">


<module type="PYTHON_MODULE" version="4">

Once I did that, even without a restart I could open the Project Structure GUI, go to Facets, and add Django from there.


2020.1 Problem importing existing project still here.
Used method suggested by Craig above, thats work as workaround.


You can do it the following way:


Then choose you Django project.

2) Go to File | Project Structure... | Modules

3) Click Add -> Import Module

4) Choose your django project again and continue in the configuration wizard and click OK at the end to save.

5) Make sure File | Project Structure... | Modules | <django_module> | Django is properly configured:



Sergey Karpov I tried your half explained method, but it did NOT work for me (IntelliJ 2020.3 Ultimate with python plugin 203.5981.165).

Here's what I tried with the steps listed that you decided to leave out for some reason:

Step 3....

  1. The window opens up with directories, the current project directory was already selected, I selected it again just to make sure and clicked ok.

Step 4, the wizard (why didn't you explain this critical step in depth? Very annoying of you)

  1. In the wizard the initial screen I selected "Create from existing sources" and clicked Next
  2. In the next screen , to the right of the project folder (which is checked), I changed "Java web" to "Python", clicked Next
  3. I selected the SDK (in my case the existing local python virtual environment) and clicked Next.
  4. In this window, I saw that Django was detected for 3 file and it was checked so I clicked Finish. 

The wizard closed, but there is still No Django module listed. I click apply and ok and waited for all the indexing processes to complete, opened up the project settings again and Django is still not listed.

Step 5.... Could not get here. Restarted IntelliJ, still not there. Did the whole thing again, still not there. FAIL.


Maybe if you properly list all your steps instead of glossing over all the important ones, this wouldn't have been a complete waste of my time after 3 years of this. Get it together.


Craig something must have changed in IntelliJ or Python plugin since my last comment. I just went through all the steps in the latest version and got a different result as well. I'll look into it.

I'm sorry for all the confusion.


Oh my. Has this situation improved, or is it still unknown how to add Django to a project in IDEA?


@Foobarbecue, this situation has not really improved any. I still find that the method I posted above back in Aug 2019 seems to work the most consistently for me. Here the permalink:


Please sign in to leave a comment.