Django is a highly used Python web framework that is strong & scalable and supports rapid development. However installing Django system-wide on your machine can result in version conflicts, dependency problems, and a messy development environment. This is where virtual environments are useful. With virtualenv, you can have isolated environments for every Django project so that you can develop smoothly and without conflicts.
In this tutorial, we will guide you through installing Django with virtualenv, from creating virtual environments to deploying Django apps. You are either a beginner or an advanced developer, and this tutorial will assist you in installing Django 5.1.7 using the best practices of today and troubleshooting tips for 2025.
Why Use Virtualenv for Django?
When a programmer works with multiple Django projects, installation dependencies can be more than just a headache. Each project might require different versions of Django or other Python packages that might conflict with one another and compromise stability or unexpectedly alter functionality. This is precisely why one needs to rely on virtualenv.
virtualenv is a wrapper around the virtual environment mechanism; it allows the user to create one isolated environment per project, so whatever is installed will not affect anything outside the virtualenv.
For example, one project may want to use Django 5.1.7, while another would still want to use a slightly older Django, maybe 5.1. Also, virtual environments greatly ease collaboration because all the exact package versions can be captured in a requirements.txt file; thus, when the developers collaborate, they can all be on the exact same setup.
Thus, virtualenv avoids installing system-wide packages, minimizes compatibility problems, and keeps a clean, sometimes ordered development environment. All this adds up to better project management, improved security, and guaranteed insistent applications running through development and deployment.
Prerequisites:
Before installing Django with virtualenv, make sure you have the following things,
1. Python 3.13.2 or later installed
2. pip installed
3. knowledge of the command-line, to run terminal commands.
If python and pip are not downloaded on your system, do so from python.org.
Installing Virtualenv on Windows/macOS/Linux
To install virtualenv, use the following command:
pip install virtualenv
Verify installation:
virtualenv --version
Creating a Virtual Environment: Isolating Your Django Project with venv
To create a virtual environment for your Django project, run:
virtualenv venv
For systems using Python 3, use:
python3 -m venv venv
This creates a venv folder in your project directory, which contains the isolated Python environment.
Activating the Virtual Environment
Windows:
venv\Scripts\activate
macOS/Linux:
source venv/bin/activate
You should see (venv) appear in your terminal, indicating the virtual environment is active.
Installing Django Inside Virtualenv
Now that your virtual environment is activated, install Django:
pip install django
Verify the installation:
django-admin --version
Understanding the venv Folder
The venv folder contains everything needed to run Python and Django in isolation. Here’s what it includes:
● bin/ (or Scripts/ on Windows) - Executable scripts, including python and pip.
● lib/ - Contains installed Python packages, including Django.
● pyvenv.cfg - Configuration file indicating the Python version used in this environment.
You should never modify these files manually. Instead, use pip to manage packages.
Creating a Django Project
Once Django is installed, create a project:
django-admin startproject myproject
Navigate into your project directory:
cd myproject
Run the development server:
python manage.py runserver
If successful, open http://127.0.0.1:8000/ to see Django’s welcome page.
Setting Up a Database
Django defaults to SQLite, but for PostgreSQL, install:
pip install psycopg2
Modify settings.py:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'mydatabase',
'USER': 'mydatabaseuser',
'PASSWORD': 'mypassword',
'HOST': 'localhost',
'PORT': '5432',
}
}
Run:
python manage.py migrate
Installing Virtualenv on Windows/macOS/Linux
Virtual environments are essential for managing dependencies in Django projects. They allow each project to have its own individual environment, preventing conflicts between different package versions.
To install virtualenv, open your terminal or command prompt and run:
pip install virtualenv
Once installed, verify the installation by checking the version:
virtualenv --version
If the version number appears, virtualenv is successfully installed, and you’re ready to create a virtual environment.
Creating a Virtual Environment: Isolating Your Django Project with `venv`
Next, let's create a virtual environment for your Django project. Go to your project directory in the terminal and execute:
virtualenv venv
For Python 3 systems, it's better to use the native `venv` module instead:
python3 -m venv venv
This command generates a new folder named `venv` within your project's directory. This will create its own environment isolated from everything else, with a separate interpreter and package installer (pip), so nothing else will be influenced by the installed packages here.
Activating the Virtual Environment
Before you can install Django, you must activate the virtual environment. The command to activate depends on your operating system:
On Windows (Command Prompt or PowerShell):
venv\Scripts\activate
On macOS/Linux:
source venv/bin/activate
Once this is activated, the command line in the terminal should have a prefix of `(venv)`, meaning you are now working within the virtual environment. Thus, all Python packages that you will be installing from now on would be contained within this environment.
Installing Django Within Virtualenv
With the virtual environment active, you can now install Django. Execute the following command:
pip install django
To verify that Django was installed successfully, check its version:
django-admin --version
If a version number is returned, well done! You now have Django installed in a virtual environment for a neat and organized development environment. You're now ready to begin creating your Django project!
Best Practices for Managing Virtual Environments:
To be able to work smoothly and avoid further troubles while working with Django, it is helpful to use its best practices while managing virtual environments. Here is important information to keep in mind while effectively managing your own virtual environments:
1. Always start the work on the Django project with the activation of the virtual environment. Whenever you run any Django commands, make sure to activate your virtual environment first. This will in turn ensure that the commands are running under the correct environment - not in the global Python installation.
For Windows:
venv\Scripts\activate
For macOS/Linux:
source venv/bin/activate
You'll know the environment is active when you see (venv) appear at the beginning of your command line.
2. Since it is necessary to track installed dependencies with every new package installed, use the command given below to create a
pip freeze > requirements.txt
comprising all installed packages. This file would be a requirement for sharing your project with others or deploying it on a server. To install dependencies from this file in another environment, just run:
pip install -r requirements.txt.
3. Exiting the Virtual Environment When Done - It is a good practice to exit from a virtual environment once you finish working on the Django project, so that in further installations you will not mistakenly install or modify the dependencies in the wrong environment.
To exit a virtual environment, just run the following command:
deactivate
The terminal prompt will change back to normal after the execution of this command, signifying that you are back out of the virtual environment. And now, you can do whatever you want with other projects without fearing to end up installing packages you never needed.
How to Deploy a Django Application
After you finish with the development and testing of your Django application, the next phase is deployment. While running Django tests on your local development server is acceptable, for production, you actually need to do a lot more with web server set-up.
A standard deployment stack for Django would include Gunicorn-a high-performance WSGI HTTP server for Python applications-and Nginx-a reverse proxy and web server aimed at improved performance, security, and serving static files so that you can take it step-by-step here.
1. Install Gunicorn
Gunicorn is a WSGI Python server that routes incoming HTTP requests to your Django application. It scales better and is more powerful compared to the Django development server.
Inside the virtual environment, install the Gunicorn,
pip install gunicorn
Run the Ginocorn server,
gunicorn --bind 0.0.0.0:8000 myproject.wsgi:application
● --bind 0.0.0.0:8000 > Listens for connections on all network interfaces at port 8000.
● myproject.wsgi:application > Points to Django’s WSGI application handler.
After running this command, your Django application is now accessible on port 8000!
2. Configure Nginx as a Reverse Proxy
Whereas Gunicorn takes care of running your Django application, it is not great for serving static files, load balancing, or application-level security configuration. Here comes Nginx. Nginx is a reverse proxy that acts to direct requests, from the client to the Gunicorn server, while taking care of serving static files, security settings, and load balancing.
To configure, open the Nginx configuration file for editing:
sudo nano /etc/nginx/sites-available/default
Replace the existing content with the following configuration:
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location /static/ {
alias /path/to/your/project/static/;
}
location /media/ {
alias /path/to/your/project/media/;
}
}
1. listen 80; > Ensures the server listens for HTTP requests.
2. server_name yourdomain.com; > Replace with your actual domain.
3. proxy_pass http://127.0.0.1:8000; > Redirects incoming traffic to Gunicorn.
4. location /static/ > Serves static files from your Django project.
5. location /media/ > Serves media files.
6. Save the file (CTRL + X, then Y, then Enter).
Restart Nginx to apply the changes:
sudo systemctl restart nginx
At this point, your Django application is now live and accessible through your domain name!
Common Errors and Fixes
Even if market setup is put into a good order, some common problems might still pop up while working on Django projects with virtual environment in place. This section aims to provide quick fixes for them.
1. Virtualenv Not Found
If you try to create or activate a virtual environment, but you received an error stating virtualenv not found, this either means that it is missing or needs upgrading.
Solution:
Reinstall or update virtualenv using:
pip install --upgrade virtualenv
Once installed, verify that virtualenv is available:
virtualenv --version
If the command returns a version number, it means the installation was successful.
2. Django Command Not Found
If Django commands like django-admin or python manage.py runserver are not recognized, it typically means that either:
● The virtual environment is not activated.
● Django is not installed within the virtual environment.
Solution:
First, ensure your virtual environment is active:
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
If the issue persists, reinstall Django within the virtual environment:
pip install django
After installation, check if Django is correctly installed:
django-admin --version
If this command outputs a Django version number, the issue is resolved.
3. Port Already in Use
When starting the Django development server using:
python manage.py runserver
You might encounter an error stating that port 8000 is already in use. This means another application is running on the same port.
Solution:
Run Django on a different port by specifying an available one:
python manage.py runserver 8080
Replace 8080 with any available port. To check which process is using port 8000, you can run:
lsof -i :8000 # macOS/Linux
netstat -ano | findstr :8000 # Windows
To free up the port, you can terminate the process using:
kill -9 # macOS/Linux
taskkill /PID /F # Windows
Replace <PID> with the process ID of the application using the port.
Conclusion:
Setting up Django with Virtualenv enacts a smooth, organized, and conflict-free development experience. The dependencies are kept isolated from each other, which reduces compatibility issues with simplified project management. Virtualenv makes life easier, whether for the beginner or seasoned developer. Some simple best practices adopted, like tracking dependencies with requirements.txt and deactivating the environment once not in use, lead to improved efficiency. Deploying on Gunicorn and Nginx just makes the Django project production-ready with promising guarantees and performance.
Though it can seem overwhelming when learning how to set up Virtualenv all while troubleshooting several common errors before even deploying your application, once you master them, you-in particular-become a confident and efficient developer. Just keep experimenting in this area, and soon it will be second nature!
Partner with Rasonix!
Rasonix dedicates itself to fulfilling your web development needs. Whether it is setting up a Django site, working with Virtualenv, or deployment, Rasonix has the solutions for expert web development, web hosting, and deployment. We provide help for a Django-based site with easy Stripe integration or eCommerce solutions capable of being fully customized. Reach Rasonix today, and let's create something wonderful together!
Subscribe Now