How to use Docker with Replit

The replit.nix and .replit files are hidden by default in the file tree. Click the three-dot menu (vertical dots) at the top of the file tree panel and select 'Show hidden files.' You should now see .replit and replit.nix in your project root alongside your source code. If replit.nix does not exist yet, you will create it in the next step. The .replit file should already exist with basic configuration.

The replit.nix file defines which system-level packages are available in your environment. This is equivalent to the RUN apt-get install lines in a Dockerfile. Open replit.nix (or create it if it does not exist) and define a deps array listing the packages you need. Each package uses the pkgs. prefix followed by the Nix package name. Search for available packages at search.nixos.org/packages to find the exact names. Common packages include language runtimes, database clients, image processing tools, and build compilers.

1{ pkgs }: {
2  deps = [
3    pkgs.nodejs-20_x
4    pkgs.python311
5    pkgs.ffmpeg
6    pkgs.imagemagick
7    pkgs.postgresql_16
8    pkgs.redis
9    pkgs.curl
10    pkgs.jq
11  ];
12}

After modifying replit.nix, you need to restart the Shell for Nix to pick up the changes and install the new packages. Type 'exit' in the Shell tab and press Enter. Replit will close the current Shell session, rebuild the Nix environment with your new packages, and open a fresh Shell. This process can take 30 seconds to several minutes depending on how many packages you added. Watch the Shell output for any error messages during the rebuild.

1# Type this in Shell to restart and rebuild the Nix environment:
2exit

The .replit file controls how your app runs, similar to a docker-compose.yml file. Open .replit and configure the entrypoint, run command, deployment settings, port mappings, and environment variables. The run command executes when you click the Run button. You can chain multiple commands with && or run multiple processes with & and wait. Environment variables can be set under [run.env] for development or in Secrets for sensitive values.

1entrypoint = "src/main.py"
2run = "pip install -r requirements.txt && python src/main.py"
3
4[nix]
5channel = "stable-24_05"
6
7[run.env]
8PYTHONPATH = "${REPL_HOME}/src"
9FLASK_ENV = "development"
10
11[deployment]
12run = ["sh", "-c", "python src/main.py"]
13build = ["sh", "-c", "pip install -r requirements.txt"]
14deploymentTarget = "cloudrun"
15
16[[ports]]
17localPort = 5000
18externalPort = 80
19
20hidden = [".config", "__pycache__", ".git", "venv"]

For simple package additions, you can skip editing replit.nix entirely and use the [nix] packages shortcut in your .replit file. This is faster for adding one or two packages but does not support advanced Nix expressions. List packages under [nix] packages as an array of strings. This approach and replit.nix are complementary; packages from both sources are installed.

1[nix]
2channel = "stable-24_05"
3packages = ["cowsay", "htop", "tree"]

Docker Compose often runs multiple services (server, worker, database) together. In Replit, you can achieve the same by using a compound run command in .replit. Use the & operator to run processes in the background and 'wait' to keep the main process alive. This is useful for running a frontend dev server alongside a backend API, or an application alongside a background worker.

1# Run a Flask API and a React frontend simultaneously
2run = "python api/server.py & cd frontend && npm start & wait"

The most common Nix error is 'nix error: building nix env: exit status 1,' often with output trimmed to the last 20 lines. This usually means a package name is wrong, the Nix channel is too old for the requested package, or an unfree package is being used without being enabled. To debug, check the error output in Shell, verify package names at search.nixos.org/packages, try updating the channel in .replit, and look for diagnostic info by running 'cat /run/replit/env/error' in Shell.

1# Diagnose Nix environment errors
2cat /run/replit/env/error
3
4# Check which Nix packages are currently installed
5nix-env -q
6
7# Search for a package name locally
8nix-env -qaP | grep -i ffmpeg