sodcalculator

10 Tech How-To

Install Django on a Linux VPS: Step-by-Step

Guide 10-50489 · Updated · Step by step

This guide walks you through installing Django on a Linux VPS, from updating the system to launching your first project. You’ll end with a working Django development environment that can be extended for production deployment. Before starting, ensure you have root or sudo access to your VPS and a basic familiarity with the Linux command line.

What You’ll Need

  • A Linux VPS (Ubuntu 22.04/24.04, Debian 11/12, or similar) with SSH access.
  • A user account with sudo privileges.
  • Python 3.8 or newer installed (check with python3 --version).
  • Basic command-line knowledge: navigating directories, editing files with nano or vim.

Step-by-Step

  1. Update your system packages. Log in via SSH and run:
    sudo apt update && sudo apt upgrade -y

    This ensures all existing software is current, reducing conflicts during installation.

  2. Install Python and pip if missing. Most modern VPS images include Python 3. If not, install it:
    sudo apt install python3 python3-pip python3-venv -y

    Verify with python3 --version and pip3 --version.

  3. Create a project directory. Choose a location for your Django project, e.g., ~/myproject:
    mkdir ~/myproject && cd ~/myproject
  4. Set up a virtual environment. Virtual environments isolate your project’s dependencies. Run:
    python3 -m venv venv

    Activate it with:

    source venv/bin/activate

    Your prompt should now show (venv).

  5. Install Django. With the virtual environment active, use pip:
    pip install django

    To install a specific version, e.g., Django 4.2 LTS, use pip install django==4.2. Check the installation with django-admin --version.

  6. Create a Django project. Run:
    django-admin startproject myproject .

    The trailing dot creates the project in the current directory. If you omit it, Django creates an extra folder.

  7. Configure allowed hosts. Edit myproject/settings.py and set ALLOWED_HOSTS to include your server’s IP or domain:
    ALLOWED_HOSTS = ['your-server-ip', 'example.com']

    For testing, you can use ['*'], but never in production.

  8. Run database migrations. Django comes with a default SQLite database. Apply initial migrations:
    python manage.py migrate
  9. Create a superuser (optional but recommended). For admin access:
    python manage.py createsuperuser

    Follow the prompts to set a username, email, and password.

  10. Test the development server. Start Django’s built-in server:
    python manage.py runserver 0.0.0.0:8000

    Visit http://your-server-ip:8000 in a browser. You should see the Django welcome page. Stop the server with Ctrl+C.

  11. Create a requirements file (for deployment). Freeze your dependencies:
    pip freeze > requirements.txt

    This file helps recreate the environment on another machine.

Common Mistakes

  • Forgetting the trailing dot in django-admin startproject myproject . – this creates an extra nested folder and complicates paths.
  • Running the development server without binding to 0.0.0.0 – if you only use runserver, it listens on 127.0.0.1, inaccessible from outside.
  • Not activating the virtual environment before running pip or manage.py commands, leading to “command not found” or installing globally.
  • Editing settings.py with ALLOWED_HOSTS left empty – Django will raise a DisallowedHost error.
  • Using sudo with pip inside a venv – this can override the venv and install packages system-wide.

Tips

  • Use a virtual environment for every project – it keeps dependencies separate and avoids version conflicts.
  • For production, use Gunicorn or uWSGI with Nginx, and serve static files with a dedicated server like WhiteNoise or a CDN.
  • Set DEBUG = False in production and configure a proper database like PostgreSQL for scalability.
  • Use python manage.py check --deploy to review security settings before going live.
  • Keep your requirements.txt updated whenever you add a new package.

Troubleshooting

  • “django-admin: command not found” – Ensure your virtual environment is active and Django is installed. Try python -m django --version.
  • “Permission denied” when creating files – Check directory ownership. Use sudo chown -R $USER:$USER ~/myproject.
  • Port 8000 already in use – Run sudo lsof -i :8000 to find the process, or use a different port: python manage.py runserver 0.0.0.0:8080.
  • DisallowedHost error – Add your server’s IP or domain to ALLOWED_HOSTS in settings.py.
  • “No module named ‘django’” – Make sure you’re in the venv and Django is installed: pip list | grep django.
  • Migrations not applying – Run python manage.py makemigrations first if you have custom models, then migrate.

Frequently Asked Questions

Do I need to install Django globally?

No. Using a virtual environment is best practice. It prevents conflicts between projects and keeps your system Python clean.

Which Django version should I install?

For production, choose the latest LTS (Long Term Support) version, such as Django 4.2 or 5.0 (check current LTS). For learning, the latest stable release works fine.

Can I use MySQL or PostgreSQL instead of SQLite?

Yes. Install the database server, then install a Python adapter (e.g., psycopg2 for PostgreSQL) and update the DATABASES setting in settings.py.

How do I deploy Django on a VPS?

Common stack: Nginx as a reverse proxy, Gunicorn as the WSGI server, and a production database. Set DEBUG=False, configure static files, and use a process manager like systemd to keep Gunicorn running.

Why does my site show “Bad Request (400)”?

This usually means ALLOWED_HOSTS is misconfigured. Ensure your domain or IP is listed exactly as requested in the browser.

How do I update Django later?

Activate your venv and run pip install --upgrade django. Then test your project thoroughly, as major version upgrades may require code changes.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →