Утилита командной строки curl отправляет запрос по адресу URL и печатает ответ сервера. Утилита поддерживает больше двадцати протоколов, среди них HTTP и HTTPS, FTP, SMTP и IMAP. Разработчику она нужна для работы с API и тестирования без браузера и Postman: отправить GET или POST, добавить заголовки, передать JSON, посмотреть код ответа.
Все команды ниже мы прогнали против маленького локального API на Python 3.14 на Windows 10: команды bash в Git Bash с curl 8.23.0, команды PowerShell в Windows PowerShell 5.1 со встроенным curl.exe 8.13.0. Вывод скопирован из этого прогона. Таблицу прогресса, которую curl рисует при сохранении в файл, мы не приводим. Опции -C, -F и -x мы не прогоняли: наш сервер не отдаёт файл кусками и не принимает загрузку формой, а прокси в опыте не было.
- Что такое curl простыми словами
- Установка curl и проверка версии
- Учебный API для опытов
- Синтаксис команды curl
- GET-запрос и заголовки ответа
- Отправка POST-запроса: форма и JSON
- Заголовки запроса и аутентификация
- Куки: сохранить и отправить
- Редиректы: -L и что происходит с POST
- Код ответа и ошибки в скриптах
- Скачать файл и загрузить файл на сервер
- curl в Windows: PowerShell, cmd и кавычки
- HTTPS, сертификаты и прокси
- Частые вопросы о curl
- Что такое curl-запрос?
- Чем curl в Linux отличается от curl.exe в Windows?
- Кто создал curl?
- Как посмотреть только код ответа?
- Как отправить файл JSON?
Что такое curl простыми словами
По сути curl работает клиентом для URL: вы даёте ему адрес и опции, он открывает соединение, отправляет запрос, получает ответ и выводит тело в терминал. Название обыгрывает «Client for URLs», а ещё читается как «see URL». Всю передачу данных выполняет библиотека libcurl, команда curl служит к ней интерфейсом командной строки.
Проект начинался в 1996 году как HttpGet бразильского разработчика Рафаэля Сагулы. Даниэль Стенберг вскоре стал его сопровождающим, после переименований в urlget и curl версия curl 4 вышла 20 марта 1998 года. Сейчас curl и libcurl пишет сообщество, а не один человек.
Где curl пригодится разработчику:
- проверить свой API, не открывая браузер и не настраивая графический клиент;
- повторить запрос из браузера: в DevTools Chrome на вкладке Network правый клик по запросу, затем Copy и Copy as cURL (так пункты подписаны в английском интерфейсе);
- скачать файл с помощью скрипта, например в cron или CI;
- увидеть сырые заголовки и код ответа, когда фронтенд показывает непонятную ошибку.
Установка curl и проверка версии
В Windows 10 curl встроен начиная со сборки 17063, на нашей машине файл лежит в C:\Windows\System32\curl.exe. В macOS он тоже есть из коробки, свежую версию можно поставить через Homebrew командой brew install curl. В Ubuntu пакет так и называется: sudo apt install curl.
Версию и набор протоколов показывает curl --version (коротко -V). Так выглядит ответ встроенного curl.exe на нашей Windows 10 в PowerShell:
curl.exe -V
curl 8.13.0 (Windows) libcurl/8.13.0 Schannel zlib/1.3.1 WinIDN
Release-Date: 2025-04-02
Protocols: dict file ftp ftps http https imap imaps ipfs ipns mqtt pop3 pop3s smb smbs smtp smtps telnet tftp ws wss
Features: alt-svc AsynchDNS HSTS HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM SPNEGO SSL SSPI threadsafe Unicode UnixSockets
В строке Protocols этой сборки нет sftp и scp, а curl 8.23.0 из Git for Windows на той же машине их поддерживает. Версия тоже важна: опция --json появилась в curl 7.82.0, а в Ubuntu 22.04 пакет curl версии 7.81.0. Прежде чем писать скрипт для сервера, посмотрите curl --version на нём.
Учебный API для опытов
Чтобы команды можно было повторить без интернета, поднимем сервер на стандартной библиотеке Python. Адрес /users отдаёт список в формате JSON и принимает новый объект методом POST, /echo возвращает то, что получил от curl (метод, тип содержимого, тело, куки, заголовок авторизации), /login ставит куку, /old делает редирект. Сохраните код в файл server.py:
# server.py: учебный API для опытов с curl, проверен на Python 3.14
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
class Handler(BaseHTTPRequestHandler):
def send_response(self, code, message=None):
# без строк Server и Date, чтобы вывод не менялся от запуска к запуску
self.send_response_only(code, message)
def answer(self, status, data, extra=None):
body = json.dumps(data).encode()
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
for name, value in (extra or {}).items():
self.send_header(name, value)
self.end_headers()
if self.command != "HEAD":
self.wfile.write(body)
def do_GET(self):
size = int(self.headers.get("Content-Length", 0))
text = self.rfile.read(size).decode()
if self.path == "/users" and self.command == "POST":
try:
self.answer(201, json.loads(text))
except ValueError:
self.answer(400, {"error": "bad json", "body": text})
elif self.path == "/users":
self.answer(200, {"users": ["Anna", "Boris"]})
elif self.path == "/echo":
info = {"method": self.command,
"type": self.headers["Content-Type"],
"body": text,
"cookie": self.headers["Cookie"],
"auth": self.headers["Authorization"]}
self.answer(200, {k: v for k, v in info.items() if v})
elif self.path == "/login":
self.answer(200, {"login": "ok"}, {"Set-Cookie": "session=abc123"})
elif self.path == "/old":
self.answer(301, {"moved": "/echo"}, {"Location": "/echo"})
else:
self.answer(404, {"error": "not found"})
do_POST = do_HEAD = do_GET
if __name__ == "__main__":
print("API: http://127.0.0.1:8000", flush=True)
HTTPServer(("127.0.0.1", 8000), Handler).serve_forever()
Запустите его в первом окне терминала и не закрывайте:
python server.py
API: http://127.0.0.1:8000
Сервер возвращает присланный объект и никуда его не записывает. Команды curl дальше выполняйте во втором окне, в той же папке.

Синтаксис команды curl
Базовый синтаксис: curl [опции] URL. Опции и адреса можно перемешивать в любом порядке. Без опций команда выполняет GET-запрос и печатает тело ответа. Основные опции, которые встретятся дальше:
| Опция | Что делает |
|---|---|
-X METHOD | меняет метод запроса, например на PUT или DELETE |
-d данные | отправляет данные методом POST как форму |
--json данные | отправляет JSON методом POST и ставит заголовки |
-H 'Имя: значение' | добавляет заголовок к запросу |
-i / -I | заголовки ответа с телом / только заголовки (запрос HEAD) |
-v | подробный вывод: что ушло на сервер и что пришло |
-o файл / -O | сохранить ответ в файл / в файл с оригинальным именем |
-L | следовать редиректам |
-b, -c | отправить куки / сохранить куки в файл |
-u user:password | Basic-аутентификация |
-F поле=@файл | загрузить файл формой multipart/form-data |
-f, -s, -S | ошибка при коде 400 и выше, тихий режим, текст ошибки в тихом режиме |
-w формат | вывести после ответа код, заголовок, время |
Полный список опций печатает команда curl --help all, руководство целиком curl --manual.
GET-запрос и заголовки ответа
Простой GET-запрос:
curl http://127.0.0.1:8000/users
{"users": ["Anna", "Boris"]}
Чтобы увидеть код ответа и заголовки вместе с телом, добавьте -i. Её полное имя --show-headers, до версии 8.10.0 она называлась --include, старое имя работает.
curl -i http://127.0.0.1:8000/users
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 28
{"users": ["Anna", "Boris"]}
-I отправляет запрос HEAD и показывает только заголовки. Флаг -v печатает и сам запрос: строки с > curl отправил, строки с < получил. Служебные строки со звёздочкой отрежем grep:
curl -s -v http://127.0.0.1:8000/users 2>&1 | grep '^[<>]'
> GET /users HTTP/1.1
> Host: 127.0.0.1:8000
> User-Agent: curl/8.23.0
> Accept: */*
>
< HTTP/1.0 200 OK
< Content-Type: application/json
< Content-Length: 28
<
Без опций curl сам ставит заголовки Host, User-Agent со своей версией и Accept: */*. Какие ещё бывают заголовки и зачем они, мы разбирали в статье про HTTP-заголовки.
Отправка POST-запроса: форма и JSON
-d отправляет данные методом POST. Метод указывать не нужно, а тип содержимого curl по умолчанию ставит как у HTML-формы:
curl -d 'name=Vera&role=dev' http://127.0.0.1:8000/echo
{"method": "POST", "type": "application/x-www-form-urlencoded", "body": "name=Vera&role=dev"}
Для REST API нужен JSON. Классический вариант: заголовок Content-Type через -H и тело через -d. С версии 7.82.0 то же делает одна опция --json, она ещё добавляет Accept: application/json:
curl -H 'Content-Type: application/json' -d '{"name": "Vera"}' http://127.0.0.1:8000/users
curl --json '{"name": "Vera"}' http://127.0.0.1:8000/users
{"name": "Vera"}{"name": "Vera"}
Ответы склеились в одну строку, потому что сервер не ставит перевод строки в конце тела. Длинный JSON удобнее держать в файле и передавать как --json @user.json. Проверять, что внутри действительно JSON, curl не будет: битое тело уйдёт на сервер как есть.
Мы не советуем писать curl -X POST -d ...: -d уже делает POST. Хуже того, метод из -X вместе с -L уходит во все запросы цепочки редиректов. -X используйте для PUT, DELETE и PATCH. Как эти методы работают в API, разобрано в статье REST API.

Заголовки запроса и аутентификация
Заголовков -H можно передать несколько, ограничения нет. Если имя совпадает с заголовком, который curl ставит сам, побеждает ваш. Токен передают заголовком Authorization, а User-Agent меняет -A:
curl -H 'Authorization: Bearer token123' http://127.0.0.1:8000/echo
{"method": "GET", "auth": "Bearer token123"}
Что ушло в заголовке User-Agent после -A, видно в подробном выводе:
curl -s -v -A 'my-script/1.0' http://127.0.0.1:8000/echo 2>&1 | grep User-Agent
> User-Agent: my-script/1.0
Для Basic-аутентификации есть -u user:password:
curl -u admin:qwerty http://127.0.0.1:8000/echo
{"method": "GET", "auth": "Basic YWRtaW46cXdlcnR5"}
Сервер получил пару admin:qwerty в кодировке Base64. Это не шифрование: Base64 раскодируется обратно без всякого ключа. Без HTTPS такой пароль мы бы не отправляли. Пароль прямо в команде лучше не писать: там, где система это позволяет, curl прячет его из списка процессов, но на короткое время он там виден другим пользователям той же системы. Укажите только имя, -u admin, и curl спросит пароль сам.
Куки: сохранить и отправить
-c файл записывает куки, которые прислал сервер, -b файл читает их и отправляет:
curl -c cookies.txt http://127.0.0.1:8000/login
{"login": "ok"}
Сервер прислал куку, curl записал её в файл. Отправляем её со следующим запросом:
curl -b cookies.txt http://127.0.0.1:8000/echo
{"method": "GET", "cookie": "session=abc123"}
Строка с кукой в самом файле:
grep session cookies.txt
127.0.0.1 FALSE / FALSE 0 session abc123
Файл в формате Netscape, поля разделены табуляцией. Одну куку можно передать и без файла: -b 'session=abc123'.

Редиректы: -L и что происходит с POST
По умолчанию curl редиректам не следует и показывает ответ 3xx как есть. С -L он идёт по адресу из заголовка Location, по умолчанию не больше 50 переходов (--max-redirs):
curl http://127.0.0.1:8000/old
curl -L http://127.0.0.1:8000/old
{"moved": "/echo"}{"method": "GET"}
Теперь отправим POST на тот же адрес:
curl -L -d 'x=1' http://127.0.0.1:8000/old
curl -L --post301 -d 'x=1' http://127.0.0.1:8000/old
{"method": "GET"}{"method": "POST", "type": "application/x-www-form-urlencoded", "body": "x=1"}
После ответов 301, 302 и 303 curl повторяет POST как GET. В прогоне выше после 301 данные формы до нового адреса не дошли. Если API ждёт POST и после редиректа, нужны --post301, --post302 или --post303. Пароль из -u при переходе на другой хост curl не передаёт.
Код ответа и ошибки в скриптах
Для curl ответ 404 или 500 не ошибка: запрос выполнен, тело получено, код выхода 0. В скрипте сломанный API пройдёт незамеченным, если не проверить код. Первый способ: -w '%{http_code}' печатает код ответа, а -o /dev/null выбрасывает тело.
code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8000/users)
if [ "$code" = 200 ]; then echo "API отвечает"; else echo "ошибка: $code"; fi
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/nope
API отвечает
404
Второй способ: -f завершает curl с кодом 22, если сервер ответил 400 и выше. Вместе с -sS таблица прогресса скрыта, а текст ошибки остаётся. --fail-with-body (с версии 7.76.0) тоже возвращает 22, но печатает тело ответа:
curl -s http://127.0.0.1:8000/nope; echo " код выхода: $?"
curl -sS -f http://127.0.0.1:8000/nope 2>&1; echo "код выхода: $?"
curl -s --fail-with-body http://127.0.0.1:8000/nope; echo " код выхода: $?"
{"error": "not found"} код выхода: 0
curl: (22) The requested URL returned error: 404
код выхода: 22
{"error": "not found"} код выхода: 22
Защита не абсолютная: при аутентификации ответы 401 и 407 могут проскочить мимо -f. Если сервер не запущен, curl выйдет с кодом 7 (Failed to connect to host). В -w можно вывести и заголовок ответа (%header{} появился в curl 7.84.0, --json в 7.82.0):
curl -s --json '{"name": "Vera"}' -w '\n%{http_code} %header{content-type}\n' http://127.0.0.1:8000/users
{"name": "Vera"}
201 application/json

Скачать файл и загрузить файл на сервер
-o имя сохраняет ответ в файл с заданным именем, -O берёт имя файла из последней части URL. Существующий файл с тем же именем curl перезапишет без вопросов.
curl -O http://127.0.0.1:8000/users
cat users
{"users": ["Anna", "Boris"]}
При сохранении в файл curl рисует в терминале таблицу прогресса, её скрывает -s. Прерванное скачивание большого файла продолжает -C -: curl сам посмотрит, сколько байт уже лежит в файле.
Загрузку файла на сервер формой делает -F 'file=@report.csv': знак @ говорит curl взять содержимое из файла, а тип содержимого будет multipart/form-data.
curl в Windows: PowerShell, cmd и кавычки
В Windows PowerShell 5.1 слово curl занято: это псевдоним Invoke-WebRequest, у которого другие параметры. Проверить легко:
(Get-Command curl).Definition
Invoke-WebRequest
Настоящую утилиту вызывайте как curl.exe. В PowerShell 7 такого псевдонима нет, в cmd и Git Bash команда curl сразу запускает утилиту. Про сам PowerShell и запуск файлов .ps1 есть отдельная статья: PowerShell скрипты.
Команду, скопированную из Linux, PowerShell 5.1 запускает, но сервер получает тело JSON без кавычек. Windows PowerShell 5.1 не сохраняет кавычки внутри строки, когда передаёт аргументы внешней программе; с версии 7.3 PowerShell их сохраняет:
curl.exe -s -H 'Content-Type: application/json' -d '{"name": "Vera"}' http://127.0.0.1:8000/users
{"error": "bad json", "body": "{name: Vera}"}
Рабочий обход: положить JSON в файл и передать его через @. Сам '@user.json' берите в кавычки, иначе PowerShell примет @ за свой оператор и не запустит команду. В русской Windows PowerShell 5.1 сообщение такое: «Оператор с символом «@» невозможно использовать для ссылки на переменные в выражении. «@user» может использоваться только как аргумент для команды. Для ссылки на переменные в выражении используйте «$user».», код ошибки SplattingNotPermitted. С кавычками команда работает:
Set-Content -Path user.json -Value '{"name": "Vera"}'
curl.exe -s --json '@user.json' http://127.0.0.1:8000/users
{"name": "Vera"}
Если не хочется думать о кавычках PowerShell, запускайте примеры из этой статьи в Git Bash: там они работают как в Linux.

HTTPS, сертификаты и прокси
С адресами https:// curl по умолчанию проверяет сертификат сервера: имя в сертификате должно совпасть с хостом из URL, а подпись принадлежать известному центру сертификации. Код выхода 60 значит, что сертификат подтвердить не удалось. Опция -k отключает проверку целиком, и соединение по HTTPS перестаёт быть защищённым. Мы не советуем ставить её даже «временно»: такую опцию легко забыть в скрипте. Для внутреннего центра сертификации передайте его сертификат опцией --cacert файл.pem. В сборках на Schannel, как у curl.exe в Windows, опция тоже работает, но для них рекомендуют добавить сертификат в хранилище корневых сертификатов Windows. Как устроены сертификаты и TLS, мы разбирали в статье как работает HTTPS.
Через прокси запрос отправляет опция -x [протокол://]хост[:порт], без протокола curl считает прокси HTTP-прокси.

Частые вопросы о curl
Что такое curl-запрос?
Это команда curl с адресом и опциями, которая описывает один HTTP-запрос: метод, заголовки, тело. Её можно скопировать в терминал и повторить, поэтому curl-запрос удобно прикладывать к описанию бага в API.
Чем curl в Linux отличается от curl.exe в Windows?
Это один проект с теми же опциями. Различаются версия, набор протоколов и TLS-библиотека конкретной сборки, всё это показывает curl -V. У curl.exe в Windows библиотека Schannel, и опции сертификатов работают с ней иначе: например, переменную окружения CURL_CA_BUNDLE такая сборка не учитывает. В PowerShell 5.1 добавляются псевдоним curl и обработка кавычек.
Кто создал curl?
Начал проект бразильский разработчик Рафаэль Сагула в 1996 году под именем HttpGet. Даниэль Стенберг вскоре стал сопровождающим, curl 4 вышел 20 марта 1998 года. Сейчас утилиту развивает сообщество.
Как посмотреть только код ответа?
curl -s -o /dev/null -w '%{http_code}\n' адрес. В PowerShell вызывайте curl.exe и вместо /dev/null пишите NUL: curl.exe -s -o NUL -w '%{http_code}\n' адрес.
Как отправить файл JSON?
curl --json @data.json адрес (в PowerShell '@data.json' в кавычках) или, для curl 7.81.0 и раньше, curl -H 'Content-Type: application/json' --data-binary @data.json адрес. Обычный -d @файл выкидывает из файла переводы строк, а --data-binary и --json отправляют его как есть.








