I’ve written about doing development on virtual machines and how to set up Vagrant to run Django. I’ve also been using PyCharm CE for awhile to do simple Python development. Now I’m doing more Django and decided to upgrade to the Professional Edition of PyCharm because of all its cool Django specific features. JetBrains touts you can use it with Vagrant, and built in features to do that. They have tutorials on configuring PyCharm to work with Vagrant and how to use it with Django, but not how to do both.
Turns out this isn’t as simple as it could be and no one has written a comprehensive tutorial on how to do it.
Here it is.
This tutorial will take you from having nothing to having a new Django PyCharm project running on a Vagrant VM.
Create Your Vagrant Virtual Machine
Since I’ve already written how to create a Vagrant VM to do Django development I’m going to assume you are at the same point you were at the end of that tutorial. You have a vagrant instance created. The vagrant directory shares a folder with the server. This article going to call that folder [VagrantFolder]. Any where you see that substitute your folder’s name.
The application I’m creating during this tutorial is called “session_manager”. You should substitute the name of your app.
Launch PyCharm PE and Set-up Vagrant
This tutorial assumes you are using the Professional Edition of PyCharm, as it is the one that has Django support in it. When you launch PyCharm, you’ll get the typical startup window, with its list of known projects and options to create a new one. Now we are going to tell PyCharm about the Vagrant we just created.
Select Configure->Preferences and select Vagrant on the left side.
The only thing you should have to change here is the value of “Instance Folder”. Point it to your [VagrantFolder].
[learn_more caption=”Side Note: Vagrant Not Per Project” state=”close”] I think it is a little strange PyCharm configures Vagrant separate from a project.
One of the main reasons I use Vagrant is so each project I’m working on has it’s own VM. This means anytime I launch a project, I’m going to want it to have its own vagrant instance. But with PyCharm, I have to come change this preference every time I change Projects.
Actually this may not be true, since a project is “connected” to the Vagrant instance via the “Python Interpreter”, which is bound to one vagrant instance. [/learn_more]
Create A New Django Project
Close the preferences and go back to the startup window and select Create New Project.
The Create New Project panel will appear for you to fill in.
- Project name: The name of your new Django Project. In my case this is “session_manager”
- Location: Click the button on the right and navigate to [VagrantFolder]/django_shared/
- Project Type: Click the button on the right and select “Django Project”
- Interpreter: Leave this on its default. (We’re going to have to change it in a minute anyway but you can’t select a remote interpreter in this box).
Click OK to save.
The Django Project Settings panel appears asking for Django specific configuration:
- Project name: Your project’s name, in my case “session_tracker”.
- Application name: This has to be different from your project name. {I thought naming them the same was a time honored – if weird – Django tradition.}. I named mine “session_tracker_app”.
- Templates Folder: I just leave it on the default.
- Enable Django admin: I’m leaving this checked for my app.
Click OK to save.
Now PyCharm will do its thing and you’ll have a new Django app/project created in your [VagrantFolder]
[learn_more caption=”Why Can’t I Create A Project With Remote Interpreter?”] While writing this I attempted to create the Python Interpreter first, but the “Config from Vagrant File” didn’t work.
Even if I had managed to create it, you can’t select a remote interpreter in the new project window anyway.
Why can’t I create the Vagrant Interpreter before the project and then select a remote during project Creation?[/learn_more]
Create a Python Interpreter For Our Vagrant
At this point we’ve configured a Vagrant machine and we’ve made a new Django project. We need to launch our VM so we, and PyCharm, can do some configuration.
Select Tools->Vagrant->Up and watch it launch your VM launch in the terminal that appears at the bottom of the project window. If this is the first time, this will take awhile.
We have a VM to run our project on, but PyCharm doesn’t know how to run a project on it. Because my Vagrant is setup to share the “django_shared” folder between the host machine and the VM, our code is on the VM. But if you hit run right now, PyCharm would attempt to run it on your host machine, not the VM. The way to change this, is via the Python Interpreter.
In PyCharm you configure which version of Python to use when running your project. By default this uses your local Interpreter, but we want it to use the one on the VM. We need to create a new Python Interpreter.
Where Is Python Installed? It Matters.
I mentioned PyCharm needs to know which Python to use to run a project. This is true on the VM as much as your local machine. In the next step you are going to be asked where python is installed on the VM.
I’ve done this a couple of times and left that path as PyCharm set it. Using the default “/usr/bin/python” made PyCharm think nothing was installed on the VM and then it would give me errors and make me install packages until it was configured right. One of the things I had to do to make it work was to tell PyCharm to install Django, even though my Vagrant file had installed Django.
That seemed so strange I decided to see where python actually was on my VM. Once I did that and set Python Interpreter Path correctly, PyCharm knew Django was installed and didn’t give me any errors.
If you – like me – do not know where python is installed on your VM do this in PyCharm:
Select Tools->Start SSH Session…
Select “Vagrant at [VagrantFolder]” from the list that appears. A terminal will open at the bottom of the screen.
Then do this:
vagrant@lucid64:~$ which python
/usr/local/bin/python
vagrant@lucid64:~$
Copy that path for use in the next step.
Create A New Python Interpreter
- Open Preferences.
- Select Project Interpreter -> Python Interpreter on the left side. You should see a list of existing Interpreters.
- Click the + button at the bottom of the list to create a new one.
- A popup list of Interpreter paths will appear for you to select from. Pick the option, “Remote…”
- When you do, you’ll get a new window to configure the Remote Python Interpreter. Click “Fill from vagrant config” and select the Vagrant file from [VagrantFolder]. PyCharm will fill in the values of the form.
- Name: Give your new interpreter a meaningful name.
- Python interpreter path: where python is installed on the VM.
Click OK to save.
[box type=”warning”] Vagrant Needs to be Up.
If you didn’t Vagrant Up before this, “Test Connection” won’t work and you’ll get a warning when closing the panel. If that happens, close prefs, and use Tools->Vagrant->Up to launch your VM.[/box]
Now PyCharm should know about your VM’s setup. It should show you a list of installed packages. If you are missing something, error messages will appear at the bottom and you can click them to install what it thinks you are missing. If there are no packages listed, try closing and reopening the Preferences window.
Click OK to close the Preferences Window.
Configure Your Project to Use the Correct Interpreter
PyCharm now knows about our VM’s Interpreter, we need to tell our project about it and configure things so it will run our Django application in our browser when we click the Run button.
- Select Run->Edit Configurations…
- Select the configuration on the right PyCharm created for us. In my case it was called “session_tracker”.
- Change “Python interpreter” to our newly created one.
- A new field will appear. Click the button next to “Path mappings”. A new window will appear to let you create your mappings.
- Vagrant shares a local directory with the VM. My Vagrant file is configured so a folder is called “django_shared” in our [VagrantFolder] locally, and “django_shared” in the home directory on the VM are the same. You need to enter the full paths of each of those in the “Edit Path Mappings” window. Click the + button to create a new mapping, then enter the values for the mapping on each side.
[learn_more caption=”I Hate Typing Paths”] I hate typing paths, so to make it easy I navigated to the local directory in the OSX Terminal and typed “pwd”, which spit out the full path. I copied that and pasted it into the left side of the Path Mapping Window.
Then I vagrant sshed into my vagrant box, navigated to the django_shared directory and executed “pwd” again. Copied that value and pasted it in the right side.
If you used my script, this value will always be “/home/vagrant/django_shared”.[/learn_more]
Click OK to save the paths.
Back in the configuration window.
- Click the checkbox to turn on “Run browser:”. Doing this will open your browser to that location whenever you run the Django application and start debugging.
- For Host: enter 0.0.0.0
This took me a long time to figure this one out. You have to set your host – which is what gets used by Django’s runserver command – to 0.0.0.0. If you leave it the default, you won’t be able to connect to Django from your machine.
Why? According to this blog post, which gave me the idea, it is “because Django webserver bounds the ip to 127.0.0.1, which is loopback in the Ubuntu guest”.
Click OK to save.
That, finally, is it. If you click run or menu Run->Run, your browser should open and you should see the default Django server message.
I just spent five hours writing this tutorial when I’d sat down to start working on my session_manager Django app. I did it because it took me forever to figure out how to make all this work and I wanted it to be easier for the next guy. Please give me feedback if you do find it useful and of course share it.
